File: node4.html

package info (click to toggle)
libforms-doc 0.88-2
  • links: PTS
  • area: non-free
  • in suites: hamm, potato, slink
  • size: 2,312 kB
  • ctags: 4,458
  • sloc: makefile: 31
file content (1211 lines) | stat: -rw-r--r-- 58,546 bytes parent folder | download | duplicates (4)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.0//EN">
<!--Converted with LaTeX2HTML 96.1 (Feb 5, 1996) by Nikos Drakos (nikos@cbl.leeds.ac.uk), CBLU, University of Leeds -->
<HTML>
<HEAD>
<TITLE>The Form Designer</TITLE>
<META NAME="description" CONTENT="The Form Designer">
<META NAME="keywords" CONTENT="forms">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<LINK REL=STYLESHEET HREF="forms.css">
</HEAD>
<BODY LANG="EN">
 <A NAME="tex2html2173" HREF="node5.html"><IMG WIDTH=37 HEIGHT=24 ALIGN=BOTTOM ALT="next" SRC="icons/next_motif.gif"></A> <A NAME="tex2html2171" HREF="forms.html"><IMG WIDTH=26 HEIGHT=24 ALIGN=BOTTOM ALT="up" SRC="icons/up_motif.gif"></A> <A NAME="tex2html2165" HREF="node3.html"><IMG WIDTH=63 HEIGHT=24 ALIGN=BOTTOM ALT="previous" SRC="icons/previous_motif.gif"></A> <A NAME="tex2html2175" HREF="node2.html"><IMG WIDTH=65 HEIGHT=24 ALIGN=BOTTOM ALT="contents" SRC="icons/contents_motif.gif"></A> <A NAME="tex2html2176" HREF="node8.html"><IMG WIDTH=43 HEIGHT=24 ALIGN=BOTTOM ALT="index" SRC="icons/index_motif.gif"></A> <BR>
<B> Next:</B> <A NAME="tex2html2174" HREF="node5.html">An overview of all </A>
<B>Up:</B> <A NAME="tex2html2172" HREF="forms.html">XForms Online Manual</A>
<B> Previous:</B> <A NAME="tex2html2166" HREF="node3.html">Using the Forms Library</A>
<BR> <P>
<H1><A NAME="SECTION04000000000000000000">The Form Designer</A></H1>
<P>
<A NAME="partfdesign">&#160;</A>
<A NAME="8319">&#160;</A>
<P>
<H1><A NAME="SECTION04100000000000000000">Introduction</A></H1>
<P>
This part of the documentation describes the <B>Form Designer</B>, a GUI builder
meant to help you interactively design dialogue forms for
use with the <B>Forms Library</B>.
This part assumes the reader is familiar with the <B>Forms Library </B> and
has read Part I of this document.
<P>
Even though designing forms is quite easy and requires only a relatively small
number of lines of C-code, it can be time consuming to figure out all
required positions and sizes of the objects. The <B>Form Designer </B> was written to 
facilitate the construction of forms. With <B>Form Designer</B>, there is no longer
any need to calculate or guess where the objects should be. The highly
interactive and WYSIWYG (what you see is what you get) nature of
the <B>Form Designer </B> relieves the application programmer from the time consuming
process of user interface construction so that he/she can concentrate
more on what the application program intends to accomplish.
<P>
<B>Form Designer </B> provides the abilities to interactively place, move and scale 
objects on a form, also the abilities to set all attributes of
an object. Once satisfactory forms are constructed, the <B>Form Designer </B> generates
a piece  of C-code that can then be included in the application
program. This piece of code will contain one procedure 
<code>create_form_xxx()</code> for each form, where <TT>xxx</TT> indicates
the form name. The application
only needs to call it to generate the form designed.
The code produced is easily readable.
<P>
The <B>Form Designer </B> also lets the user identify each object with C variables
for later reference in the application program and allows advanced
object callback bindings all within the <B>Form Designer</B>.
All actions are performed with the mouse or the function keys. 
It uses a large number of forms itself to let the user make choices,
set attributes, etc. Most of these forms were designed using 
the <B>Form Designer </B> itself.
<P>
It is important to note that the <B>Form Designer </B> only helps you in designing 
the layout of your forms. It does not allow you to specify the 
actions that have to be taken when, e.g., a button is pushed. You 
can indicate the callback routine to call but the application program 
has to supply this callback routine. Also, the current version
is mostly a layout tool and not a programming environment,
not yet anyway. This means that the <B>Form Designer </B> does not allow you 
to initialize all your objects. You can, however, initialize
some objects, e.g., you can set the bounds of a 
slider inside the <B>Form Designer</B>. Eventually full support of object
initialization will be implemented.
<P>
<H1><A NAME="SECTION04200000000000000000">Getting started</A></H1>
<P>
To start up the <B>Form Designer </B> simply type <code>fdesign</code> without any argument.
(If nothing happens, check whether the package has been installed 
correctly.) A black window (the main window) will appear on the screen. This is 
the window in which you can create your forms. 
Next the control panel appears on the screen.  No form is shown yet.
<P>
<CENTER>
<P><A NAME="1396">&#160;</A><A NAME="figfdesign">&#160;</A> <IMG WIDTH=820 HEIGHT=366 ALIGN=BOTTOM ALT="figure1393" SRC="img17.gif"  > <BR>
<STRONG>Figure 8.1:</STRONG> <B>Form Designer </B> control panel<BR>
<P>
</CENTER>
<P>
The control panel consists of five parts (see Fig.&nbsp;<A
HREF="node4.html#figfdesign">8.1</A>). The first part is the menu bar
consisting of several groups of menus from which you can make selections or
give commands to the program. At the left there is a list of forms you are
working on.  The list is empty, indicating that there are no forms yet. You
can work on up to 64 forms at the same moment. You can use this list to
switch from form to form.  To the bottom of that there is a list of all
groups in the form you are working on. It will be empty because there are no
groups.  Ignore this at the moment as we will come back to groups and their
use later.  Next to this you find a list of all different types of objects
that can be placed on the forms. You can use the mouse to select the type of
object you want to add to the form.  At the right you find a number of
buttons to give commands to the program. Each of these buttons is bound to a
function key.  You can either press the buttons with the mouse or press the
function keys on the keyboard. This will have the same effect.  The
functions of these keys will be described below.
<P>
To create a new form click with the mouse on the button labeled 
<SMALL CLASS=SMALL><I>New Form</SMALL></I> on the top-left corner of the control panel just below 
the menu bar.  A little notifier will appear prompting you for the name 
of the form. This is the name under which the application program will 
know the form.  You will have to provide a name (which must be a legal C 
or C++ variable name). Type in the name and press &lt;R<font size=-1><small>ETURN</small></font>&gt;.  Now the 
background of the form appears in the main window. Note the form name is 
added in the list of forms in the control panel.
<P>
To add an object to the form, choose the type of object in the control panel
by clicking in the list of object classes.
Next move the mouse into the form you are creating and drag the
mouse while pressing the left mouse button. Keep the mouse
button pressed and create a box that has the desired size. Release the
button and the object will appear.  Note that a red
outline appears around the new object. This means that the object is selected.
In this way you can put all kinds of objects on the form.
<P>
It is possible to move objects around or change their size. To this end,
first select the object by pressing the mouse in it. A red
outline will appear around the object. Now, dragging a mouse button
will move the object. By grabbing the object at one of the 
four red corners you can scale it. In this way you can change the layout 
of the objects on the form. It is also possible to select multiple 
objects and move or scale them simultaneously. See below for details.
<P>
To change the attributes, e.g., the label, of an object, click the
mouse inside the object to select it. Next, press the function
key &lt;F1&gt; (either on the keyboard or in the control form) or
click on the <SMALL CLASS=SMALL><I>Attrib</SMALL></I> in the control panel. This
can also be achieved by double-clicking the right mouse button.
A form will appear in which you can indicate
all the different attributes. Their meanings should be clear
(if you have read the documentation on the <B>Forms Library</B>). Change the attributes by
pressing a mouse button on them. A menu will appear in which you can
make the required choice.  Change the attributes you want to change
and press the button labeled <SMALL CLASS=SMALL><I>Accept</SMALL></I>. 
Press <SMALL CLASS=SMALL><I>Restore</SMALL></I> to  restore the
original attributes. See below for more information about changing
attributes.
<P>
In this way you can create the forms you want to have. Note that you can work
on different forms at the same moment. Just add another form in the way
described above and use the list of forms to switch between them.
After you have created all your forms choose <I>Save</I> from the
<SMALL CLASS=SMALL><I>File</SMALL></I> menu to save them to disk.
It will ask you for a file name using the file selector. In this 
file selector you can walk through the directory tree to locate 
the place where you want to save the file. Next, you can type in 
the name of the file (or point to it when you want to overwrite an 
existing file). The name should end with <code>.fd</code>.  So for example, 
choose <code>ttt.fd</code>. The program now creates three files: 
<code>ttt.c</code>, <code>ttt.h</code> and <code>ttt.fd</code>.  <code>ttt.c</code> contains 
a readable piece of C code that creates the forms you designed. The 
file <code>ttt.h</code> contains the corresponding header file for inclusion 
in your application program.
The file <code>ttt.fd</code> contains a description of the
forms in such a way that the <B>Form Designer </B> can read it back in later.
The application program now simply has to call the routine
<code>create_form_xxx()</code> to create the different forms you designed.
<P>
These are the basic ideas behind the <B>Form Designer</B>. Below we describe
the program in detail.
<P>
<H1><A NAME="SECTION04300000000000000000">Command line arguments</A></H1>
<P>
To start the <B>Form Designer </B> simply type
<P>
<PRE>   fdesign [-xformoptions] [-fdesignoptions] [files[.fd]]</PRE>
<P>
An initial window will be created and mapped. Depending on the
window manager, you may have the option to interactively select
where to place the window if <TT>-geometry</TT> option is missing.
Next the program places the control panel on the
screen. You can move this panel, if required, to the place you want
(you can also change the default placement of the control
panel via resources).
<P>
<code>fdesign</code> accepts all of the <B>XForms </B> command line options as well
as the following 
<A NAME="1410">&#160;</A>
<P>
<DL ><DT><STRONG>-geometry <EM>geom</EM></STRONG>
<DD>
This option specifies the initial placement and size of the working area.
<P>
<DT><STRONG>-convert <EM>fd-file-list</EM></STRONG>
<DD> 
Normally <code>fdesign</code> does its work interactively. This option causes 
the <code>fdesign</code> simply read a list of <code>fdesign</code> output 
file (the <TT>.fd</TT> files) and emit the corresponding C-routines and 
header files.
<P>
<DT><STRONG>-version</STRONG>
<DD> Prints current version and quits.
<DT><STRONG>-help</STRONG>
<DD> Prints a brief help message on command line options.
<P>
<DT><STRONG>-altformat</STRONG>
<DD> Generates an alternative output format.
<P>
<DT><STRONG>-border</STRONG>
<DD> Forces decorations on several windows so that you
can move them easily.
<P>
<DT><STRONG>-unit <I>point</I>|<I>pixel</I>|<I>mm</I>|<I>cp</I>|<I>cmm</I></STRONG>
<DD>
Outputs object sizes in units other than pixels.
<TT>cp</TT> and <TT>cmm</TT> stand for centi-point (1/100 of a point)
and centi-mm (1/100 of a milli-meter). 
<A NAME="1417">&#160;</A><A NAME="1418">&#160;</A>
For typical displays, <I>pixel</I> and <I>mm</I> are too coarse
and subject to round-off errors.
<P>
<DT><STRONG>-nocode</STRONG>
<DD>
Suppresses the output of UI code. This can be handy if the
UI code is not generated interactively, but rather generated by the 
<I>make</I> process using <code>fdesign -convert</code>.
<P>
<DT><STRONG>-I header</STRONG>
<DD>
Changes the output include file from <code>forms.h</code> to
<code>header</code>. Useful on systems where <code>forms.h</code> is
renamed to something else or you need application
specific constants/defines for the UI to function. In
the later case, <TT>header</TT> may simply contain
<P>
<PRE>#include &quot;forms.h&quot;
#define mystuff 1</PRE>
<P>
<DT><STRONG>-main</STRONG>
<DD>
Emits a main program with callback stubs. Can be useful for
simple programs.<A NAME="1421">&#160;</A>
<P>
<DT><STRONG>-callback</STRONG>
<DD>
Emits callback function template in a separate file.
<P>
<DT><STRONG>-lax</STRONG>
<DD>
Suppresses syntax checking on variable and callback function names.
<P>
<DT><STRONG>-bw <EM>borderwidth</EM></STRONG>
<DD>
Changes default border width of the forms created.
<P>
 </DL>
<P>
Note that <TT>-help, -version and -convert</TT> do not
require a connection to an X server.
<P>
If an output unit other than the default (<TT>pixel</TT>) is selected,
all object sizes in the output file will be in the unit requested.
This kind of UI has a fixed and device resolution independent
size (in theory at least) and can be useful for drawing applications.
<P>
<code>fdesign</code> recognizes the following resources
<A NAME="1426">&#160;</A>
<P>
<TABLE COLS=3>
<COL ALIGN=LEFT><COL ALIGN=LEFT><COL ALIGN=LEFT>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
    workingArea.geometry </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Geometry     </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> string </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> 
    control.border       </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> XForm.Border </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> bool   </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> 
    control.geometry     </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Control.Geometry </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> string (position only)</TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> 
    attributes.geometry  </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Attributes.Geometry </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> string (position only)</TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> 
    attributes.background</TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Attributes.Background </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> string (e.g.,gray80)</TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> 
    align.geometry       </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Align.Geometry </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> string (position only)</TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> 
    help.geometry        </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Help.Geometry </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> string (position only)</TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> 
    convert              </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Convert      </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> bool   </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> 
    unit                 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Unit         </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> string </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> 
    altformat            </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> AltFormat    </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> bool   </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> 
    xformHeader          </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> XFormHeader  </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> string </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> 
    helpFontSize         </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> HelpFontSize </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> int    </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> 
    main                 </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Main         </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> bool </TD></TR>
</TABLE>
<P>
Note that resource specification of <TT>convert</TT> requires an X connection.
<P>
In addition, all <B>XForms</B>'s resources specification can be used to
influence the appearance of various panels. The most useful
ones are the font sizes
<P>
<TABLE COLS=2>
<COL ALIGN=LEFT><COL ALIGN=LEFT>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
   *XForm.FontSize  </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> all label font sizes </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> 
   *XForm.PupFontSize  </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> all pup font sizes
</TD></TR>
</TABLE>
<H1><A NAME="SECTION04400000000000000000">Creating Forms</A></H1>
<P>
<H1><A NAME="SECTION04410000000000000000">Creating, changing and deleting forms</A></H1>
<P>
To create a new form press the button labeled <SMALL CLASS=SMALL><I>New Form</SMALL></I>, indicate the
enclosing box of the form and type in a (unique) name for the form. The
form is shown in the main window and objects can be added to it.
<P>
There are two ways to change the size of a form at a later stage. The
easiest way is to simply change the size of the main window and the form will 
resize itself to fit the new size. Or you can select the bottom box of the 
form, using the right mouse button. Next grab the box using the middle mouse 
at the lower-right corner and scale it.  Note that objects lying outside the 
form will be invisible when the form is shown by the application program.
<P>
To change the name of the current visible form, press the button labeled
<SMALL CLASS=SMALL><I>Rename Form</SMALL></I> under the list of forms.
You will be prompted for the new form name.
<P>
To delete a form, press the button labeled <SMALL CLASS=SMALL><I>Delete Form</SMALL></I>. The current
form will be removed.
<P>
<H1><A NAME="SECTION04420000000000000000">Adding objects</A></H1>
<P>
<A NAME="1440">&#160;</A>
To add an object, choose the class of the object from the object list  
in the middle of the control panel. Next drag the left mouse button
on the form and an outline showing the current size of the object
will appear. When the size is correct release the mouse button.
<P>
Note that the position and size of the object is rounded to multiples of
10 pixels. This can be changed. See below on alignments.
<P>
<H1><A NAME="SECTION04430000000000000000">Selecting objects</A></H1>
<P>
<A NAME="1442">&#160;</A>
To perform operations on objects that are already visible in the form, we
first have to select them. Any mouse button can be used for selecting
objects. Simply click it inside the object you want to select. A red outline
will appear, indicating that the object is selected.
In some cases when the currently selected object is large and encloses
some smaller objects in it, left mouse might not be able to select
the enclosed small objects. In this, use the the right mouse.
Another way of selecting objects is to use the &lt;<font size=-1><small>TAB</small></font>&gt; key
or the &lt;F11&gt; or the button labeled <SMALL CLASS=SMALL><I>F11</SMALL></I>,
which walks down the object list and selects an object upon each
press.<A NAME="1446">&#160;</A>
<P>
It is also possible to select multiple objects. To this end, 
draw a box by dragging the mouse around all the objects you want to select.
All objects that lie fully inside the box will be selected. Each selected
object will get a red outline and a red bounding box is drawn around all of
them.
<P>
To add objects to an already existing selection, hold down the &lt;S<font size=-1><small>HIFT</small></font>&gt; key
and press the right mouse button inside the objects. You can remove objects
from the selection by doing the same on an already selected object.
<P>
It is possible to select all objects (except for the backface) at once using
the function key &lt;F4&gt;.<A NAME="1449">&#160;</A>
<P>
One note on the backface of the form. Although this is a normal object, it
can not be treated in the same way as the other objects. It can be selected,
but never in combination with other objects. Only two operations are allowed
on it: changing its attributes and scaling it (which scales the size of the
form).
<P>
<H1><A NAME="SECTION04440000000000000000">Moving and scaling</A></H1>
<P>
<A NAME="1451">&#160;</A>
Moving and scaling of objects is done using the middle mouse button.
To move an object or a collection of objects to a new place, first select it
(them) using the right mouse button as described above. Next press the middle
mouse button inside the bounding box (not near one of the corners) and move
the box to its new position.
<P>
<A NAME="1452">&#160;</A>
To scale the object or objects, pick up the bounding box near one of its
corners (inside the red squares) and scale it.
<P>
When holding the &lt;S<font size=-1><small>HIFT</small></font>&gt; key while moving an object or group of objects,
first a copy of the object(s) is made and the copy is moved. This allows for a
very fast way of duplicating (cloning)  objects on the form: First put one
on the form, change the attributes as required and next copy it.
<P>
For precise object movement, the cursor keys can be used. Each 
pressing of the four directional cursors moves the object 5 pixels. 
To change the step size,  precedes the cursor keys with <code>0-9</code> with
<code>0</code> indicating <TT>10</TT> pixels. If &lt;S<font size=-1><small>HIFT</small></font>&gt; is down,
instead of moving the object, the object size is increased or
decreased by the step size.<A NAME="1456">&#160;</A>
<P>
<H1><A NAME="SECTION04450000000000000000">Aligning objects</A></H1>
<P>
<A NAME="1458">&#160;</A>
<P>
Sometimes you have a number of objects and you want to align them in some way,
e.g. centered or all starting at the same left position, etc. To this end
press the button labeled <SMALL CLASS=SMALL><I>Align</SMALL></I>. A special form will appear in the top
right corner. You can leave this form visible as long as you want. You can
hide it using the button <SMALL CLASS=SMALL><I>Dismiss</SMALL></I> on the form or by clicking 
button <SMALL CLASS=SMALL><I>Align</SMALL></I> again.
<A NAME="1462">&#160;</A>
<P>
Now select the objects you want to align. Next, press one of the alignment
buttons in the form. The buttons mean 
top row: flush
left, horizontal center, flush right, horizontal equal distance (see below),
bottom row: align bottoms, vertical center, align tops, vertical equal
distance. Note that alignments are relative to the selection box,
not to the form.
Equal distance alignment means that between all the objects an
equal sized gap is placed.
The objects are kept in the same left to right or bottom to top order.
<P>
<CENTER>
<P><A NAME="1466">&#160;</A> <IMG WIDTH=471 HEIGHT=182 ALIGN=BOTTOM ALT="figure1463" SRC="img18.gif"  > <BR>
<STRONG>Figure 10.1:</STRONG> Object alignment control<BR>
<P>
</CENTER>
<P>
In the alignment form you can also indicate the snapping size using the
counter at the bottom.
Choose 0 if you don't want to snap positions. Default snapping is 10
pixels.  Snapping helps in making objects
the same size and in making them nicely aligned.
<P>
The <SMALL CLASS=SMALL><I>Undo</SMALL></I> undoes the last alignment change. It is an undo
with a depth of 1, i.e., you can only undo the last change and
an undo after an undo will undo itself.
Note however, Any modification to the selected objects invalidates the
undo buffer.
<P>
<H1><A NAME="SECTION04460000000000000000">Raising and lowering</A></H1>
<P>
<A NAME="fdesignraising">&#160;</A>
<P>
<A NAME="1471">&#160;</A>
The objects in a form are drawn in the order in which they are added.
Sometimes this is undesirable. For example, you might decide at a later stage
to put a box around some buttons. Because you add this box later, it will be
drawn over the buttons thus making the buttons invisible
(if you put a framebox over a button, the button will be visible
but appears to be inactive!).
This is definitely not what you want. The <B>Form Designer </B> makes it
possible to raise objects (bring them to the top) or lower them (put them at
the bottom). So you can lower the box to move it under the buttons. Raising or
lowering objects is very simple. First select the objects using the right
mouse button and next press the function key &lt;F2&gt; to lower the selection
or &lt;F3&gt; to raise it.
<P>
Another use of raising and lowering is to change the input
field visitation order (via &lt;T<font size=-1><small>AB</small></font>&gt; key).<A NAME="1475">&#160;</A>
<A NAME="1476">&#160;</A>
Input fields focus order is the same as the order in which
they are added to the form. This can become a problem 
if another input field is needed after the form is designed
<P>
because this extra input field will always be the last
among all input field on the form. Raising the objects
becomes handy to solve this problem. What really happens
when a object is raised is that the raised object
becomes the last object added to the form. This means
you can re-arrange the focus order by raising all input fields 
one by one in the exact order you want the focus order to be,
and they will be added to the form in the order you raise
them, thus the input focus order.
<P>
<H1><A NAME="SECTION04470000000000000000">Setting attributes</A></H1>
<P>
<A NAME="1478">&#160;</A>
<P>
To set attributes like type, color, label, etc., of an object first select it
(using the right mouse button) and next press the function key &lt;F1&gt;
(or click on the button labeled <SMALL CLASS=SMALL><I>F1</SMALL></I>).
If only one object is selected you can change all its attributes, including
its label, name, etc. It is also possible to change the attributes of multiple
objects as long as they all are of the same class. In this case you cannot
change the label, name, etc. because you probably want them to remain
different for the objects.
<P>
A form will appear in which you can indicate the different settings.
Before we continue, the organization of the Attribute form and
classification of attributes need a little explanation.  
Attributes of an object are divided into two categories. The Generic
attributes are shared by all objects. These include type, color,
label, callback functions etc. The Specific attributes are those
that are specific to a particular object class, such as 
slider bounds, precision etc. When the Attribute form is first shown,
only the Generic attributes are shown. Press on folder <SMALL CLASS=SMALL><I>Spec</SMALL></I>
to activate the object class specific attributes part 
(and press on button <SMALL CLASS=SMALL><I>Generic</SMALL></I> to switch back to 
the generic attributes part).
<P>
<H1><A NAME="SECTION04480000000000000000">Generic Attributes</A></H1>
<P>
<H2><A NAME="SECTION04481000000000000000">Colors</A></H2>
<P>
Here you can indicate type, boxtype, and colors of the object, and style,
size, alignment and color of the label. The type, boxtype, style, size and
alignment are set using a choice object. To change it either use the left or
middle mouse button to cycle through the possibilities, or use the right mouse
button to get a menu with all choices.
To change one of the colors, push the mouse on it.
A box will appear showing the available colors
in the internal color map. You can indicate the color you want with 
the mouse or use cancel to keep the color unchanged. (The color of the 
cancel button is the current color you are changing.) You can use the arrows 
to run through the color map to find other colors.
<P>
Once you are satisfied with the settings, press the button labeled 
<SMALL CLASS=SMALL><I>Ready</SMALL></I> and the form will disappear. If you don't want to change 
the attributes after all press the button labeled <SMALL CLASS=SMALL><I>Cancel</SMALL></I>.
<P>
<H2><A NAME="SECTION04482000000000000000">Object names and call-back routines</A></H2>
<P>
Three more fields can be filled in in the attributes form: name, callback
and argument. Name indicates the name of the object. If you type in a name here
the object will be known to the application program under this name so that
the program can refer to it. Take care that all object names used are
different. They should be legal C variable names.<A NAME="tex2html650" HREF="footnode.html#1488"><IMG  ALIGN=BOTTOM ALT="gif" SRC="icons/foot_motif.gif"></A> It is possible to use 
arrays of objects. E.g. if you define some objects as 
<code>obj[0]</code>, <code>obj[1]</code> and <code>obj[2]</code> the piece of C-code 
produced by the <B>Form Designer </B> will contain a declaration of an array 
<code>tt</code> of size 3. (Only one-dimensional arrays are treated correctly.)
<P>
Callback indicates the callback routine.
If you type in something here, this routine will be bound to the object. In
this case you also have to provide an argument that must be an integer
(or cast to integer, as in <code>(long)&amp;variable</code>).
Of course, the application program will have to provide the callback
routine.<A NAME="1489">&#160;</A>
<P>
Note that when copying objects these fields are also copied. This might lead
to multiple objects with the same name. This will lead to undesired effects. 
So watch out for these after copying an object.
<P>
<H1><A NAME="SECTION04490000000000000000">Object Specific Attributes</A></H1>
<P>
Currently not all objects can be initialized from with the <B>Form Designer</B>.
<P>
Depending on the objects, different attributes are shown that are
considered to be intrinsic to the objects, such as slider bounds,
precision etc. All the attributes should be self-explanatory
and all changes made are shown immediately so you can see
what effects the changes have on the object.
Once satisfactory results are achieved, press button <SMALL CLASS=SMALL><I>Accept</SMALL></I>
to accept the settings (press on the folder <SMALL CLASS=SMALL><I>Generic</SMALL></I>
has the same effect). Two additional buttons <SMALL CLASS=SMALL><I>Cancel</SMALL></I>
and <SMALL CLASS=SMALL><I>Restore</SMALL></I> are available to cancel the changes (and
quit the attributes setting form) and restore the defaults, respectively.
<P>
One particular aspect of the pixmap/bitmap button initialization needs a
little more explanation as the setting of button <SMALL CLASS=SMALL><I>Use
data</SMALL></I> has no effect on the appearance of the button but
nonetheless affects the generated code. By default, button <SMALL
CLASS=SMALL><I>Use data</SMALL></I> is false, indicating the pixmap/bitmap
file specified is to be loaded dynamically at run time via
<code>fl_set_pixmapbutton_file()</code> (or the bitmap counterpart). If
<SMALL CLASS=SMALL><I>Use data</SMALL></I> is true, the specified file and
its associated data will be <code>#include</code>'d at compile time so the
data is part of the code. Depending on the application setup, you may choose
one method over the other. In general, including the data in the code will
make the code slightly larger, but it avoids the problems with not finding
the specified file at runtime. The button <SMALL CLASS=SMALL><I>Full
Path</SMALL></I> only applies if <SMALL CLASS=SMALL><I>Use Data</SMALL></I>
is true. If <SMALL CLASS=SMALL><I>Full Path</SMALL></I> is true, the pixmap
file will be <code>#include</code>d using the full path otherwise only the
filename is used, presumably the compile process will take care of the path
via <code>-I</code> flag in some system dependent way. In general, not using
the full path is more flexible.
<P>
<H1><A NAME="SECTION044100000000000000000">Cut, Copy and Paste</A></H1>
<P>
<A NAME="1502">&#160;</A>
<P>
You can remove objects from the form by first selecting them and next 
pressing function key &lt;F12&gt; or double-clicking the left mouse button. 
The objects will disappear but are in fact saved in a buffer. You can put 
them back in the form, or in another form, by pasting them using 
&lt;F10&gt;. Note that only the last collection of deleted objects is 
saved in the buffer.
<P>
It is also possible to put a copy of the selection in the buffer using
&lt;F9&gt;. This selection can now be put into the same form or into a
different form. This allows for a simple mechanism of making multiple copies
of a set of objects and for moving information from one form to another.
<P>
To clone the currently selected object, hold down the &lt;S<font size=-1><small>HIFT</small></font>&gt;
key and drag the selected object. The cloned object will
have exactly the same attributes as the original object
except for object name and shortcut keys. Should these
be cloned, the generated code would not be compilable
(or cause runtime misbehavior).
<P>
<H1><A NAME="SECTION044110000000000000000">Groups</A></H1>
<P>
<A NAME="1508">&#160;</A>
<P>
As described in the tutorial about the <B>Forms Library</B>, sets of radio
buttons must be placed inside groups. Groups are also useful for other
purposes. E.g. you can hide a group inside an application program
with one command. Hence, the <B>Form Designer </B> has some mechanism to deal with groups.
<P>
In the control panel there is a list of groups in the current form. As long as
you don't have groups, this list will be empty. To create a group, select the
objects that should come in the group and press the function key 
&lt;F7&gt;. You will be prompted for the name of the group. This should be 
a legal C variable name (under which the group will be known to the 
application program) or should be empty. This name will be added to the
list. In this way you can create many groups. Note that each object can be in
only one group. So if you select it again and put it in a new group, it will
be removed from its old group. Groups that become empty this way automatically
disappear from the list. (When putting objects in a group they will be raised.
This is unavoidable due to the structure of groups.)
<P>
In the list of groups it is always indicated which groups are part of the
current selection. (Only the groups that are fully contained in the selection
are indicated, not those that are only partially contained in it.) It is also
possible to add or delete groups in the current selection by pushing the mouse
on their name in the list.
<P>
Note that there is no mechanism to add an object to a group directly. 
This can, however, be achieved using the following procedure. Select 
the group and the new object and press
&lt;F7&gt; to group them. The old group will be discarded and a 
new group will be created. You only have to type in the group name again.
<P>
Sometimes you want to un-group the objects in an existing group, i.e., get them
out of the group they are currently in. To this end simply select the group
and press &lt;F8&gt;. (This only works if one group is selected.)
<P>
You can use the item <I>Rename group</I> under the <SMALL CLASS=SMALL><I>Group</SMALL></I>
menu to change the name of a selected group. If multiple groups are 
selected only the name of the first group is changed.
<P>
<H1><A NAME="SECTION044120000000000000000">Hiding and showing</A></H1>
<P>
Sometimes it is useful to temporarily hide some objects in your form. In
particular when you have sets of overlapping objects. To this end, select the
objects you want to hide and press &lt;F6&gt;. The objects (though still
selected) are now invisible. To show them again press &lt;F5&gt;. A problem 
might occur here. When you press &lt;F5&gt; only the selected objects will be 
shown again. But once an object is invisible it can no longer be selected.
Fortunately, you can always use &lt;F4&gt; to select all objects, including the
invisible ones, and press &lt;F5&gt; after that. It is better, though,
to first group the
objects before hiding them. Now you can select them by pressing the mouse on
the group name in the group browser.
<P>
<H1><A NAME="SECTION044130000000000000000">Testing forms</A></H1>
<P>
<A NAME="1521">&#160;</A>
<P>
To test the current form, press the button labeled <SMALL CLASS=SMALL><I>Test</SMALL></I>. The form
will be displayed in the center of the screen. A panel will appear at the top
right corner of the screen. This panel will show you the objects that will be
returned and the callback routines called when working with the form. In this
way you can verify whether the form behaves correctly and whether all objects
have either callback routines or names (or both) associated with them.
You can also resize the form (if the backface of the form allows
resizing) to test the gravities.  You can play with the form as long 
as you want.  When ready, press the button <SMALL CLASS=SMALL><I>Stop Testing</SMALL></I>.
<P>
Note that any changes you made, including the size of the form,
to the form while testing do not show up when saving the form. 
E.g. filling in an input field or setting a slider does not mean 
that in the saved code the input field will be filled in or the slider set.
<P>
<H1><A NAME="SECTION04500000000000000000">Saving and loading forms</A></H1>
<P>
To save the set of forms created select the item <I>Save</I> 
or <I>Save As</I> from the <SMALL CLASS=SMALL><I>File</SMALL></I> menu.  You will be prompted 
for a file name using the file selector if the latter
is selected. Choose a name that ends with <code>.fd</code>.
e.g. <code>ttt.fd</code>.
<P>
The program will now generate three files <code>ttt.c</code>,
<code>ttt.h</code> and <code>ttt.fd</code>. If these files already
exist, backup copies of these are made (by
appending <code>.bak</code> to the file names).
<code>ttt.c</code> contains a piece of C-code that builds up the
forms and <code>ttt.h</code> contains all the object and form
names as indicated by the user. It also contains declaration
of the defined callback routines.
<P>
Depending on the options selected from the <SMALL CLASS=SMALL><I>Options</SMALL></I> 
menu, two more files may be emitted. Namely the 
main program and callback function templates. They are
named <code>ttt_cb.c</code> and <code>ttt_main.c</code> respectively. 
<A NAME="1529">&#160;</A>
<P>
There are two different kind of formats for the C-code
generated. The default format allows more than one instances
of the form created and uses no global variables. The other
format, activated by <code>altformat</code> on the command line,
or from the <SMALL CLASS=SMALL><I>Options</SMALL></I> menu by selecting <I>Alt Format</I>,
uses global variables and does not allow more than one
instantiation of the designed forms. However, this format
has a global routine that creates all the forms defined,
which by default is named <code>create_the_forms()</code> but it 
can be changed (see below).
<P>
Depending on which format is output, the application program
typically only needs to include the header file and call
the form creation routine.
<P>
To illustrate the differences between the two output formats
and the typical way an application program is setup, we look at
the following hypothetical situation: We have two forms, 
<TT>foo and bar</TT>, each of which contains several objects,
say <TT>fnobj1, fnobj2</TT> etc.&nbsp; where <TT>n=1,2</TT>. The default output
format will generate the following header file (<code>foobar.h</code>):
<P>
<PRE>   #ifndef FD_foobar_h_
   #define FD_foobar_h_

   /* call back routines if any */
   extern void callback(FL_OBJECT *,long);

   typedef struct
   {
        FL_FORM *foo;
        void *vdata;
        char *cdata;
        long  ldata;
        FL_OBJECT *f1obj1;
        FL_OBJECT *f1obj2;
   } FD_foo;

   typedef struct
   {
        FL_FORM *bar;
        void *vdata;
        cahr *cdata;
        long  ldata;
        FL_OBJECT *f2obj1;
        FL_OBJECT *f2obj2;
   } FD_bar;

   extern FD_foo *create_form_foo(void);
   extern FD_bar *create_form_bar(void);

   #endif /* FD_foobar_h */</PRE>
<P>
and the corresponding C file:
<P>
<PRE>   #include &quot;forms.h&quot;
   #include &quot;foobar.h&quot;

   FD_foo *create_form_foo(void)
   {
       FD_foo *fdui = (FD_foo *) fl_calloc(1, sizeof(FD_foo));

       fdui-&gt;foo = fl_bgn_form(....);
       fdui-&gt;f1obj1 = fl_add_xxxx(....);
       .....
       fl_end_form();

       fdui-&gt;foo-&gt;fdui = fdui;
       return fdui;
   }

   FD_bar *create_form_foo(void)
   {
       FD_bar *fdui = (FD_bar *) fl_calloc(1, sizeof(FD_bar));

       fdui-&gt;bar = fl_bgn_form(....);
       fdui-&gt;f2obj1 = fl_add_xxxx(....);
       .....
       fl_end_form();

       fdui-&gt;bar-&gt;fdui = fdui; 
       return fdui;
   }</PRE>
<P>
The application program would look something like the following:
<P>
<PRE>   #include &quot;forms.h&quot;
   #include &quot;foobar.h&quot;

   /* add call back routines here */

   main(int argc, char *argv[])
   {
       FD_foo *fd_foo;
       FD_bar *fd_bar;

       fl_initialize(...);
       fd_foo = create_form_foo();
       init_fd_foo(fd_foo);        /* application UI init routine */

       fd_bar = create_form_bar();
       init_fd_bar(fd_bar)         /* application UI init routine */

       fl_show_form(fd_foo-&gt;foo, ...);
       /* rest of the program */
   }</PRE>
<P>
As you see, <TT>fdesign</TT> generates a structure that groups
together all objects on a particular form and the form itself
into a structure for easy maintenance and access.  The
other benefit of doing this is that the application program 
can create more than one instances of the form if needed.
<P>
It is difficult to avoid globals in an event-driven callback scheme with 
the most difficulties occurring inside the callback function where another 
object on the same form may need to be accessed. Current setup makes it 
possible and relatively painless to achieve this.
<P>
There are a couple of ways to do this. The easiest and most
robust way is to use the member <TT>form-&gt;fdui</TT>, 
<A NAME="6865">&#160;</A>
which <TT>fdesign</TT> is set to pointing to the <code>FD_</code> structure
in which the <TT>form</TT> is member. To illustrate how this
is done, let's take the above two forms and try to access
a different object from within a callback function.
<P>
<PRE>   fdfoo = create_form_foo();
   ...</PRE>
<P>
and in the callback function of <TT>ob</TT> on form <TT>foo</TT>, you can access 
other objects as follows:
<P>
<PRE>   void callback(FL_OBJECT *ob, long data)
   {
      FD_foo *fdfoo = ob-&gt;form-&gt;fdui;
      fl_set_object_xxx(fdfoo-&gt;f1obj2, ....);
   }</PRE>
<P>
Of course this setup still leaves the problems accessing
objects on other forms unsolved although you can manually
set the <TT>form-&gt;u_vdata</TT> to the other <code>FD_</code>
structure: <code>fd_foo-&gt;form-&gt;u_vdata</code> <TT>= fd_bar</TT> or
use the <code>vdata</code> field in the <code>FD_</code> structure
itself: <code>fd_foo-&gt;vdata</code> <TT>= fd_bar</TT>.
<P>
The other method, not as easy as using <TT>form-&gt;fdui</TT> (because
you get no help from <TT>fdesign</TT>), but just as workable, 
is simply use the <code>u_vdata</code> in <code>FD_</code> structure to
hold the ID of the object that needs to be accessed. In case
of a need to access multiple objects, 
there is a field <code>u_vdata</code> in both <code>FL_FORM</code> 
and <code>FL_OBJECT</code> structures you can use. You simply use the 
field to hold the <code>FD_</code> structure:
<P>
<PRE>   fdfoo = create_form_foo();
   fdfoo-&gt;foo-&gt;u_vdata = fdfoo;
   ...</PRE>
<P>
and in the callback function, you can access other objects
as follows:
<P>
<PRE>   void callback(FL_OBJECT *ob, long data)
   {
      FD_foo *fdfoo = ob-&gt;form-&gt;u_vdata;
      fl_set_object_xxx(fdfoo-&gt;f1obj2, ....);
   }</PRE>
<P>
Not pretty, but adequate for practical purposes. Note that
the FD structure always has the form as the
first entry and followed by <TT>vdata</TT>, <TT>cdata</TT> and <TT>ldata</TT>.
Also a struct <code>FD_Any</code> is defined in the <code>forms.h</code>:
<P>
<A NAME="6866">&#160;</A>
<A NAME="6867">&#160;</A>
<P>
<PRE>   typedef struct 
   {
       FL_FORM *form;
       void *vdata;
       char *cdata;
       long  ldata;
   } FD_Any;
\end{vernatim}

you can use to cast a specific \verb+FD_+ structure get
to the \var{vdata}. 

Another alternative is to use the \verb+FD_+ structure
created as the user data in the callback

\index{object!fl_set_object_callback@{\verb+fl_set_object_callback+}}
\begin{verbatim}
   fl_set_object_callback(obj, callback, (long)fdui);</PRE>
<P>
and use the callback as follows<A NAME="tex2html659" HREF="footnode.html#1555"><IMG  ALIGN=BOTTOM ALT="gif" SRC="icons/foot_motif.gif"></A>
<P>
<PRE>   void callback(FL_OBJECT *ob, long arg)
   {
       FD_foo *fdfoo = (FD_foo *) arg;

       fl_set_object_lcol(fdfoo-&gt;f1obj1, FL_RED);
       ...
    }</PRE>
<P>
Avoiding globals is, in general, a good idea, but as everything
else, an excess of a good thing can be bad. Sometimes, 
simply making the <TT>FD_</TT> structure global makes a program
clearer and more maintainable.
<P>
There still is another difficulty that might arise with
the current setup. For example, in <TT>f1obj1</TT>'s callback
we change the state of some other objects , say,
<TT>f1obj2</TT> via <code>fl_set_button/input</code>. Now the state
of <TT>f1obj2</TT> is changed and it needs to be handled.
You probably don't want to put too much <TT>f1obj2</TT>'s handling
code in <TT>f1obj1</TT>'s callback. In this situation,
the following function comes in handy
<P>
<A NAME="6868">&#160;</A>
<A NAME="6869">&#160;</A>
<PRE>   void fl_call_object_callback(FL_OBJECT *obj)</PRE>
<P>
<code>fl_call_object_callback(fdfoo-&gt;f1obj2)</code> will invoke
the <TT>f1obj2</TT>'s callback in exactly the same way the
main loop would and as far as <TT>f1obj2</TT> is concerned,
it just handles the state change as if the user changed it.
<P>
The alternative format outputs something like the following:
<P>
<PRE>   /* callback routines */
   extern void callback(FL_OBJECT *, long);

   extern FL_FORM *foo, *bar;
   extern FL_OBJECT *f1obj1, f1obj2 ...;
   extern FL_OBJECT *f2obj1, f2obj2 ...;

   extern void create_form_foo(void), create_form_bar(void);
   extern void create_the_forms(void);</PRE>
<P>
The C-routines:
<P>
<PRE>   FL_FORM *foo, *bar;
   FL_OBJECT *f1obj1, *f1obj2 ...;
   FL_OBJECT *f2obj1, *f2obj2 ...;

   void create_form_foo(void)
   {
      if(foo)
        return;
      foo = fl_bgn_form(....);
      ...
   }

   void create_form_bar(void)
   {
      if(bar)
        return;
      bar = fl_bgn_form(....);
      ...
   }

   void create_the_forms(void)
   {
       create_form_foo();
       create_form_bar();
   }</PRE>
<P>
Normally the application program would look something like this:
<P>
<PRE>   #include &quot;forms.h&quot;
   #include &quot;foobar.h&quot;

   /* The call back routines */

   main(int argc, char *argv[])
   {
     fl_initialize(....);
     create_the_forms();
     /* rest of the program */
   }</PRE>
<P>
Note that although the C-routine file in both cases is easily readable,
editing it is strongly discouraged. If you were to do so, you will have 
to redo the changes whenever you call <TT>fdesign</TT> again to modify
the layout.
<P>
The third file created, <code>ttt.fd</code>, is in a format that can be
read in by the <B>Form Designer</B>. It is easy readable ASCII but you had better not 
change it because not much error checking is done when reading it in.
To load such a file select the <I>Open</I> from the <SMALL CLASS=SMALL><I>File</SMALL></I>
menu.  You will be prompted for a file name using the file
selector. Press your mouse on the file you want to load and press the button
labeled <SMALL CLASS=SMALL><I>Ready</SMALL></I>.  The current set of forms will be discarded, and
replaced by the new set. You can also merge the forms in a file with the
current set. To this end select <I>Merge</I> from the
<SMALL CLASS=SMALL><I>File</SMALL></I> menu.
<P>
<H1><A NAME="SECTION04600000000000000000">Language Filters</A></H1>
<P>
<A NAME="1574">&#160;</A>
This chapter discusses the language filter support in <B>Form Designer</B>, targeted
<A NAME="1575">&#160;</A>
primarily to the developers of other language bindings to
<B>Forms Library</B>. As of this writing, the authors are aware of  the following
bindings
<P>
<UL><LI> <TT>ada95</TT> binding by  G.&nbsp;Vincent Castellano (<code>gvc@ocsystems.com</code>),<LI> <TT>perl</TT> binding by  Martin Bartlett (<code>martin@nitram.demon.co.uk</code>),<LI> <TT>Fortran</TT> binding by  G.&nbsp;Groten 
   (<code>zdv017@zam212.zam.kfa-juelich.de</code>) and
   Anke Haeming (<code>A.Haeming@kfa-juelich.de</code>), and<LI> <TT>pascal</TT> binding by Michael Van Canneyt
(<code>michael@tfdec1.fys.kuleuven.ac.be</code>)<LI> <TT>python</TT> binding by  Roberto Alsina 
   (<code>ralsina@ultra7.unl.edu.ar</code>).
    It would appear that author of  <TT>python</TT> binding  is no longer
    working on it.
</UL>
<A NAME="1584">&#160;</A>
<A NAME="1585">&#160;</A>
<A NAME="1586">&#160;</A>
<A NAME="1587">&#160;</A>
<A NAME="1588">&#160;</A>
<A NAME="1589">&#160;</A> 
<A NAME="1590">&#160;</A> 
<A NAME="1591">&#160;</A> 
<A NAME="1592">&#160;</A> 
<A NAME="1593">&#160;</A>
<P>
These bindings are of varying degree of beta-ness and support. It 
appears to the authors that the most convenient and flexible way of getting
output in the targeted language is through external filters
that are invoked transparently by the fdesign. This way, 
developers of the binding would have complete control over the
translation of the default output from the fdesign
to the target language and at the same time have the
translation done transparently.
<P>
<H1><A NAME="SECTION04610000000000000000">External filters</A></H1>
<P>
An external filter is a stand-alone program that works
on the output of <B>Form Designer</B>, and translates the output to the
target language. The filter can elect to work on the .fd or the c
output or both simultaneously. However, in non-testing
situations, the c output from <B>Form Designer </B> probably should be
deleted by the filter once the translation is complete.
<A NAME="1595">&#160;</A>
<P>
By default, <B>Form Designer </B> only outputs the .fd and c files. If
the presence of <TT>-ada</TT>,
<TT>-perl</TT>, <TT>-python</TT>, <TT>-fortran</TT> or <TT>-pascal</TT> command 
line options to <B>Form Designer</B> is detected, then after emitting the default 
output, <B>Form Designer </B> invokes the the external filter with the root filename 
(without the .fd extension)
as an argument, together with possible other flags, to the filter.
Any runtime error messages
are presented to the user in a browser. The filter name
by default is <TT>fd2xxxx</TT> where <TT>xxxx</TT> is the language
name (such as <TT>fd2python</TT> etc.), which can be changed
using the <TT>-filter</TT> command line option (or equivalent 
resources).
<P>
The resources that are relevant to the filter are listed below
<P>
<TABLE COLS=3>
<COL ALIGN=LEFT><COL ALIGN=LEFT><COL ALIGN=LEFT>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
Resource </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Type </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> Default </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> 
language  </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> string </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> C </TD></TR>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> 
filter    </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> string </TD><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP> None
</TD></TR>
</TABLE>
<H1><A NAME="SECTION04620000000000000000">Command line arguments of the filter</A></H1>
<P>
<B>Form Designer </B> passes along the options that affect the output format to
the filter. These options may or may not apply to the filter,
most likely not if the filter works on the C file.
For those that do not apply, the filter can simply ignore them,
but shouldn't stop  running because of these options.
<P>
<DL ><DT><STRONG>-callback</STRONG>
<DD>   callback stubs are generated.
<DT><STRONG>-main</STRONG>
<DD>       main stub is generated.
<DT><STRONG>-altformat</STRONG>
<DD>  output in alternate format
<DT><STRONG>-compensate</STRONG>
<DD> emit size compensation code
<P>
 </DL><H1><A NAME="SECTION04700000000000000000">Generate hardcopies of the interface</A></H1>
<P>
<A NAME="chfd2ps">&#160;</A>
<P>
A variety of tools are available that can be used to turn
your carefully constructed (and hopefully pleasing) user
interfaces into printed hardcopies or something appropriate
for inclusion in your program document. Most of these involves 
saving a snapshot of your interface on the screen into
a file. Then this file is translated into something that a 
printer can understand, such as PostScript. While this
approach works, the resulting file is typically
huge. Further, by taking a snapshot of the screen,
the resolution of the output is limited by the
screen resolution, which typically is much lower than
the printer resolution. This is especially evident
for text.
<P>
Another approach is to design the printing capabilities
into the objects themselves so the GUI is somewhat output
device independent in that it can render to different
devices and X or the printer is just one of the devices. While this 
approach works better than screen snapshot, in general, it bloats the 
library unnecessarily.  It is our observation that  most
of the time when a hardcopy of the interface is desired,
it is for use in the application documentation. Thus
we believe that there are ways to meet the
needs of wanting hardcopies without bloating the library.
Of course, some objects, such as xyplot, charts
and possibly canvas (if vector graphics), that
are dynamic in nature, probably should have
some hardcopy output support in the library, even then,
the relevant code should only be loaded when these specific support 
is actually used. This fattening problem is becoming less 
troublesome as computers are faster and typically with more
RAMs on them nowadays.
<P>
<B>fd2ps</B> was designed to address the need of having a hardcopy of 
<A NAME="1614">&#160;</A>
the interface  for application documentation development.
Basically, <B>fd2ps</B> is a translator that translates
the <B>Form Designer </B> output directly into PostScript or Encapsulated PostScript
in full vector graphics. The  result is a small, may even be
editable, PostScript file that you can print on a printer
or include into other documents.
<P>
The translation can be done in two ways. One way is to simply
give the <B>Form Designer </B> the command line option <I>-ps</I> to have it
output P<font size=-1><small>OST</small></font>S<font size=-1><small>CRIPT</small></font> directly or you can run the <B>fd2ps</B>
stand alone <TT>fd2ps fdfile</TT> where <TT>fdfile</TT> is the
<B>Form Designer </B> output with or without the <TT>.fd</TT> extension. The output
is written into a file named <TT>fdfile.ps</TT>.
<P>
The <B>fd2ps</B> accepts the following command line options when
run stand alone
<P>
<DL ><DT><STRONG>-h</STRONG>
<DD> This option prints a brief help message.
  <DT><STRONG>-p</STRONG>
<DD> This options requests Portrait output. By default, the
        orientation is switched to landscape automatically
        if the output would not fit on the page. This option
        overrides the default.
 <DT><STRONG>-l</STRONG>
<DD> This option requests landscape orientation.
 <DT><STRONG>-gray</STRONG>
<DD> This option requests all colors be converted
           to gray levels. By default, <B>fd2ps</B> outputs
           colors as specified in the <TT>.fd</TT> file.
 <DT><STRONG>-bw <I>n</I></STRONG>
<DD> This option specifies the object border
                   width. By default, the border width specified
                   in the <TT>.fd</TT> file is used.
 <DT><STRONG>-dpi <I>f</I></STRONG>
<DD> This option specifies the screen resolution
                 on which the user interface was designed.
                 You can use this flag to enlarge or shrink the
                 designed size by giving a DPI value smaller
                 or larger than the actual screen resolution.
                 The default DPI is 85. If the <TT>.fd</TT> file
                 is specified in device independent unit
                 (point, mm etc), this flag has no effect. Also
                 this flag does not change text size.
 <DT><STRONG>-G <I>f</I></STRONG>
<DD> This option specifies a value (gamma) that will 
         be used to adjust the builtin colors. Larger the
         value, bright the colors. The default gamma is 1.
 <DT><STRONG>-pw <I>f</I></STRONG>
<DD> This option changes the paper width used to
              center the GUI on a printed page. By default, the
              width is that of US Letter (i.e., 8.5 inches) unless
             the environment variable <TT>PAPER</TT> is defined.
 <DT><STRONG>-ph <I>f</I></STRONG>
<DD> This option changes the paper height used to
             center the output on the printed page. The default
             height is that of US Letter (i.e., 11 inches) unless
            the environment variable <TT>PAPER</TT> is defined.
 <DT><STRONG>-paper <I>name</I></STRONG>
<DD> This option specifies one of the standard
     paper names (thus setting the paper width and height simultaneously).
     The current understood papers are listed below.
<TABLE>
<TR><TD>Letter</TD><TD>8.5 x 11 inch.</TD></TR>
<TR><TD>Legal </TD><TD>8.5 x 11 inch.</TD></TR>
<TR><TD>A4    </TD><TD>210 x 295 mm.</TD></TR>
<TR><TD>B4    </TD><TD>257 x 364 mm.</TD></TR>
<TR><TD>B5    </TD><TD>18 x 20 cm.</TD></TR>
<TR><TD>B     </TD><TD>11 x 17 inch.</TD></TR>
<TR><TD>Notes </TD><TD>4 x 5 inch.</TD></TR>
</TABLE>
<P>
  The <B>fd2ps</B> program understands the environment variable
  <TT>PAPER</TT>, which should be one of the above paper names.
<P>
 </DL>
<P>
<A NAME="8477">&#160;</A>
<HR><A NAME="tex2html2173" HREF="node5.html"><IMG WIDTH=37 HEIGHT=24 ALIGN=BOTTOM ALT="next" SRC="icons/next_motif.gif"></A> <A NAME="tex2html2171" HREF="forms.html"><IMG WIDTH=26 HEIGHT=24 ALIGN=BOTTOM ALT="up" SRC="icons/up_motif.gif"></A> <A NAME="tex2html2165" HREF="node3.html"><IMG WIDTH=63 HEIGHT=24 ALIGN=BOTTOM ALT="previous" SRC="icons/previous_motif.gif"></A> <A NAME="tex2html2175" HREF="node2.html"><IMG WIDTH=65 HEIGHT=24 ALIGN=BOTTOM ALT="contents" SRC="icons/contents_motif.gif"></A> <A NAME="tex2html2176" HREF="node8.html"><IMG WIDTH=43 HEIGHT=24 ALIGN=BOTTOM ALT="index" SRC="icons/index_motif.gif"></A> <BR>
<B> Next:</B> <A NAME="tex2html2174" HREF="node5.html">An overview of all </A>
<B>Up:</B> <A NAME="tex2html2172" HREF="forms.html">XForms Online Manual</A>
<B> Previous:</B> <A NAME="tex2html2166" HREF="node3.html">Using the Forms Library</A>
<P><ADDRESS>
<H6>&#169; 1996, 1997 <A HREF="mailto:dau@westworld.com">Danny Uy</A>,<I>DropDead, Inc.</I></H6>
</ADDRESS>
</BODY>
</HTML>