-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdialogs.html
1826 lines (1744 loc) · 109 KB
/
dialogs.html
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
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<TITLE>dialogs.h</TITLE>
<STYLE TYPE="TEXT/CSS">
<!--
.IE3-DUMMY { CONT-SIZE: 100%; }
BODY { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; BACKGROUND-COLOR: #E0E0E0; }
P { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H1 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H2 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H3 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H4 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H5 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H6 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
UL { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
TD { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; BACKGROUND-COLOR: #FFFFFF; }
.NOBORDER { BACKGROUND-COLOR: #E0E0E0; PADDING: 0pt; }
.NOBORDER TD { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; BACKGROUND-COLOR: #E0E0E0; PADDING: 0pt; }
.CODE { FONT-FAMILY: Courier New; }
-->
</STYLE>
</HEAD>
<BODY TEXT="#000000" BGCOLOR="#E0E0E0">
<FONT SIZE="5"><B>The <dialogs.h> Header File</B></FONT>
<HR>
<P><B>Routines for creating dialogs</B></P>
<H3><U>Functions</U></H3>
<DL INDENT="20"><DT><B><A HREF="#Dialog">Dialog</A></B><DD>Shows and activates a dialog box given a pointer to a dialog structure.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#DialogAdd">DialogAdd</A></B><DD>Adds an item into a dialog box.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#DialogAddDynamicPulldown">DialogAddDynamicPulldown</A></B><DD>Adds a dynamic pulldown menu into a dialog box.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#DialogAddDynamicRequest">DialogAddDynamicRequest</A></B><DD>Adds a request/edit box with a dynamic buffer into a dialog box.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#DialogAddMenu">DialogAddMenu</A></B><DD>Adds a menu into a dialog box.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#DialogAddPulldown">DialogAddPulldown</A></B><DD>Adds a pulldown/popup menu into a dialog box.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#DialogAddPulldownEx">DialogAddPulldownEx</A></B><DD>Adds a pulldown/popup menu into a dialog box. Extended version.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#DialogAddRequest">DialogAddRequest</A></B><DD>Adds a request/edit box into a dialog box.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#DialogAddRequestEx">DialogAddRequestEx</A></B><DD>Adds a request/edit box into a dialog box. Extended version.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#DialogAddScrollRegion">DialogAddScrollRegion</A></B><DD>Adds a rectangular item-scrolling region to a dialog box.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#DialogAddStaticPulldown">DialogAddStaticPulldown</A></B><DD>Adds a static pulldown/popup menu into a dialog box.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#DialogAddText">DialogAddText</A></B><DD>Adds a text into a dialog box.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#DialogAddTextEx">DialogAddTextEx</A></B><DD>Adds a text, an image, or a custom item into a dialog box.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#DialogAddTitle">DialogAddTitle</A></B><DD>Adds a title bar and up to two buttons into a dialog box.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#DialogAddTitleEx">DialogAddTitleEx</A></B><DD>Adds a title/header bar and up to two buttons into a dialog box. Extended version.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#DialogAddXFlags">DialogAddXFlags</A></B><DD>Adds extended dialog properties into a dialog box.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#DialogDo">DialogDo</A></B><DD>Activates and shows a dialog box.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#DialogNew">DialogNew</A></B><DD>Creates a new dialog box which can interact with the user program.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#DialogNewSimple">DialogNewSimple</A></B><DD>Creates a new dialog box.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#DlgMessage">DlgMessage</A></B><DD>Displays a message dialog box.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#HI_WORD">HI_WORD</A></B><DD>Returns the high word from a long value.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#LO_WORD">LO_WORD</A></B><DD>Returns the low word from a long value.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#NoCallBack">NoCallBack</A></B><DD>Dummy callback function doing nothing.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#VarNew">VarNew</A></B><DD>Displays the standard "New" dialog.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#VarOpen">VarOpen</A></B><DD>Displays the standard "Open" dialog.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#VarSaveAs">VarSaveAs</A></B><DD>Displays the standard "Save Copy As" dialog.</DL>
<H3><U>Constants</U></H3>
<DL INDENT="20"><DT><B><A HREF="#CENTER">CENTER</A></B><DD>A constant to describe a centered position for dialogs.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#DialogMessages">DialogMessages</A></B><DD>An enumeration to describe messages used by a Dialog's Callback.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="alloc.html#H_NULL">H_NULL</A></B><DD>A null-handle value.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="alloc.html#NULL">NULL</A></B><DD>A null-pointer value.</DL>
<H3><U>Predefined Types</U></H3>
<DL INDENT="20"><DT><B><A HREF="alloc.html#Bool">Bool</A></B><DD>An enumeration to describe true or false values.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#Buttons">Buttons</A></B><DD>An enumeration to describe possible button types.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#Dialog_Callback_t">Dialog_Callback_t</A></B><DD>Callback function type for dialogs.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#Dialog_GetHandle_t">Dialog_GetHandle_t</A></B><DD>Callback function type returning a handle for a dialog item.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#DIALOG_ITEM">DIALOG_ITEM</A></B><DD>A scructure for defining dialog items.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#DIALOG_STRUCT">DIALOG</A></B><DD>A scructure for defining dialogs.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#DialogFlags">DialogFlags</A></B><DD>An enumeration to describe possible item flags in a dialog box.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#DialogTypes">DialogTypes</A></B><DD>An enumeration to describe possible item types in a dialog box.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#DialogXFlags">DialogXFlags</A></B><DD>An enumeration to describe possible XFlags in a dialog box.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="estack.html#ESQ">ESQ</A></B><DD>Represents a quantum within an expression.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="alloc.html#HANDLE">HANDLE</A></B><DD>Represents a handle associated with an allocated memory block.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="vat.html#HSym">HSym</A></B><DD>A structure representing a symbol reference.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#OWNER_DRAW_STRUCT">OWNER_DRAW_STRUCT</A></B><DD>A scructure for defining an owner draw item.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="graph.html#SCR_RECT">SCR_RECT</A></B><DD>A scructure for defining a rectangular area.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="graph.html#SCR_STATE">SCR_STATE</A></B><DD>A structure for saving the state of the graphics system.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="wingraph.html#WINDOW">WINDOW</A></B><DD>The main window-describing structure.</DL>
<H3><U>Other Identifiers</U></H3>
<DL INDENT="20"><DT><B><A HREF="#SIZED_DIALOG">SIZED_DIALOG</A></B><DD>A macro to help defining dialogs, it is nearly the same as DIALOG.</DL>
<P><B>Note:</B> If your program uses functions from this header file, you probably have to
define <CODE><A HREF="httigcc.html#advanced_fileinuse">SET_FILE_IN_USE_BIT</A></CODE>.</P>
<HR>
<H3><A NAME="Dialog"><U>Dialog</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#short">short</A></B> Dialog (<A HREF="#DIALOG_STRUCT">DIALOG</A> *DialogPtr, <B><A HREF="keywords.html#short">short</A></B> x, <B><A HREF="keywords.html#short">short</A></B> y, <B><A HREF="keywords.html#int">char</A></B> *RequestBuffer, <B><A HREF="keywords.html#short">short</A></B> *PopupBuffer);</TD></TR></TABLE></P>
<P><B>Shows and activates a dialog box given a pointer to a dialog structure.</B></P>
<P>Dialog works exactly like <A HREF="#DialogDo">DialogDo</A>, except instead of the
handle, a pointer to the dialog structure is given as the parameter.
<A HREF="#DialogDo">DialogDo</A> internally calls <A HREF="alloc.html#HeapDeref">HeapDeref</A>,
then passes the returned pointer to the Dialog function. This function is mainly used
internally in TIOS. Its advantage compared to <A HREF="#DialogDo">DialogDo</A> is
the fact that the complete dialog structure may be given as a static pre-filled
array of bytes, and you can give a pointer to such a structure to the Dialog function.
It will save a lot of memory, because you do not need to call <A HREF="#DialogNew">DialogNew</A> and
a lot of functions like <A HREF="#DialogAddText">DialogAddText</A> etc.
<BR><BR>
If DialogPtr points to a dynamically created dialog box (i.e a dialog created with <A HREF="#DialogNew">DialogNew</A>
or <A HREF="#DialogAdd">DialogAdd</A>), the heap block that stores the dialog box must be locked
because <I>this routine may cause heap compression</I>.
<BR><BR>
Dialog may return:</P>
<UL><LI><P><CODE>KEY_ENTER</CODE> if the user pressed ENTER to close the dialog box.</P></LI>
<LI><P><CODE>KEY_ESC</CODE> if the user pressed ESC to close the dialog box.</P></LI>
<LI><P><CODE>-1</CODE> if there is not enough memory to open the menu for the dialog box.</P></LI></UL>
<P>See also: <A HREF="#DialogDo">DialogDo</A></P>
<HR>
<H3><A NAME="DialogAdd"><U>DialogAdd</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><A HREF="alloc.html#HANDLE">HANDLE</A> DialogAdd (<A HREF="alloc.html#HANDLE">HANDLE</A> Handle, <B><A HREF="keywords.html#short">short</A></B> flags, <B><A HREF="keywords.html#short">short</A></B> x, <B><A HREF="keywords.html#short">short</A></B> y, <B><A HREF="keywords.html#short">short</A></B> ItemType, ...);</TD></TR></TABLE></P>
<P><B>Adds an item into a dialog box.</B></P>
<P>DialogAdd is a universal item-adding function. It is a very complicated
function which accepts 6 to 12 parameters depending on the type of the item
which will be added. This type is determined by the <I>ItemType</I>
parameter. In fact, all other functions whose names begin with "DialogAdd..."
(such as <A HREF="#DialogAddTextEx">DialogAddTextEx</A>,
<A HREF="#DialogAddTitleEx">DialogAddTitleEx</A>,
<A HREF="#DialogAddRequestEx">DialogAddRequestEx</A>,
<A HREF="#DialogAddPulldownEx">DialogAddPulldownEx</A>, etc.) are
implemented as macros which call DialogAdd with appropriate parameters (for
easier usage), so you can mainly avoid this function. You can read the
<CODE>dialogs.h</CODE> header file to see how exactly these macros are
implemented.
<BR><BR>
The order of item creation is very important, as it automatically gives each
item an identification number (the first created item will get an
identification number of 0, the second one will get 1, and so on). Every
function that creates an item (i.e. every function beginning with
'DialogAdd...') will increase this identification number.
<BR><BR>
DialogAdd returns <A HREF="alloc.html#H_NULL">H_NULL</A> in case of an
error, may return <A HREF="#DialogMessages">DB_MEMFULL</A> if you used
<A HREF="#DialogFlags">DF_SCREEN_SAVE</A>, else returns <I>Handle</I>.
This routine (as well as all other 'DialogAdd...' routines) may cause heap
compression.
<BR><BR>
<I>ItemType</I> can be filled with one of the following commands, defined in
the <A HREF="#DialogTypes">DialogTypes</A> enum:
<BR><BR>
<TABLE BORDER CELLPADDING="3">
<TR>
<TD><B><I>ItemType</I></B></TD>
<TD><B>Appearance</B></TD>
<TD><B>Additional Parameters</B></TD>
<TD><B>Macro</B></TD>
</TR>
<TR>
<TD VALIGN="TOP">D_HEADER</TD>
<TD VALIGN="TOP">Title bar, up to two buttons</TD>
<TD VALIGN="TOP"><CODE>const char *title, unsigned short LeftButton, unsigned short RightButton</CODE></TD>
<TD VALIGN="TOP"><A HREF="#DialogAddTitleEx">DialogAddTitleEx</A></TD>
</TR>
<TR>
<TD VALIGN="TOP">D_TEXT</TD>
<TD VALIGN="TOP">Text or personalized item</TD>
<TD VALIGN="TOP"><CODE>const char *text</CODE></TD>
<TD VALIGN="TOP"><A HREF="#DialogAddTextEx">DialogAddTextEx</A></TD>
</TR>
<TR>
<TD VALIGN="TOP">D_EDIT_FIELD</TD>
<TD VALIGN="TOP">Request (edit) box</TD>
<TD VALIGN="TOP"><CODE>const char *label, unsigned short offset, unsigned short MaxLen, unsigned short width</CODE></TD>
<TD VALIGN="TOP"><A HREF="#DialogAddRequestEx">DialogAddRequestEx</A></TD>
</TR>
<TR>
<TD VALIGN="TOP">D_HEDIT</TD>
<TD VALIGN="TOP">Request (edit) box</TD>
<TD VALIGN="TOP"><CODE>const char *label, unsigned short width</CODE></TD>
<TD VALIGN="TOP"><A HREF="#DialogAddDynamicRequest">DialogAddDynamicRequest</A></TD>
</TR>
<TR>
<TD VALIGN="TOP">D_POPUP</TD>
<TD VALIGN="TOP">Pulldown menu</TD>
<TD VALIGN="TOP"><CODE>const char *label, void *Popup, unsigned short buffer</CODE></TD>
<TD VALIGN="TOP"><A HREF="#DialogAddStaticPulldown">DialogAddStaticPulldown</A></TD>
</TR>
<TR>
<TD VALIGN="TOP">D_DYNPOPUP</TD>
<TD VALIGN="TOP">AMS 2.00 or higher: Pulldown menu</TD>
<TD VALIGN="TOP"><CODE>const char *label, Dialog_GetHandle_t GetPopup, unsigned short index</CODE></TD>
<TD VALIGN="TOP"><A HREF="#DialogAddDynamicPulldown">DialogAddDynamicPulldown</A></TD>
</TR>
<TR>
<TD VALIGN="TOP">D_HPOPUP</TD>
<TD VALIGN="TOP">Pulldown menu</TD>
<TD VALIGN="TOP"><CODE>const char *label, HANDLE MenuHandle, unsigned short index</CODE></TD>
<TD VALIGN="TOP"><A HREF="#DialogAddPulldownEx">DialogAddPulldownEx</A></TD>
</TR>
<TR>
<TD VALIGN="TOP">D_MENU</TD>
<TD VALIGN="TOP">AMS 2.00 or higher: Main menu</TD>
<TD VALIGN="TOP"><CODE>void *Menu, unsigned short MaxMenuWidth</CODE></TD>
<TD VALIGN="TOP"><A HREF="#DialogAddMenu">DialogAddMenu</A></TD>
</TR>
<TR>
<TD VALIGN="TOP">D_SCROLL_REGION</TD>
<TD VALIGN="TOP">Scroll region</TD>
<TD VALIGN="TOP"><CODE>unsigned short x1, unsigned short y1, unsigned short FirstItem, unsigned short LastItem, unsigned short NumDspItems, unsigned short TotNumItems, unsigned short ItemHeight</CODE></TD>
<TD VALIGN="TOP"><A HREF="#DialogAddScrollRegion">DialogAddScrollRegion</A></TD>
</TR>
<TR>
<TD VALIGN="TOP">D_XFLAGS</TD>
<TD VALIGN="TOP">AMS 2.00 or higher: Extended dialog properties</TD>
<TD VALIGN="TOP"><CODE>unsigned short xFlags1, unsigned short xFlags2, unsigned short xFlags3, unsigned short xFlags4</CODE></TD>
<TD VALIGN="TOP"><A HREF="#DialogAddXFlags">DialogAddXFlags</A></TD>
</TR>
</TABLE>
<BR>
The parameter <I>flags</I> depends on the type of element you are creating
and can be a combination of the following flags, defined in the
<A HREF="#DialogFlags">DialogFlags</A> enum:
<BR><BR>
<TABLE BORDER CELLPADDING="3">
<TR>
<TD><B>Flag</B></TD>
<TD><B>Item Type</B></TD>
<TD><B>Description</B></TD>
</TR>
<TR>
<TD VALIGN="TOP">DF_SCREEN_SAVE</TD>
<TD VALIGN="TOP">(any)</TD>
<TD>When applied to the first item in the dialog, the dialog code saves the
area underneath the dialog box when it is started. DialogAdd returns
<A HREF="#DialogMessages">DB_MEMFULL</A> if there is not enough
memory to do this.</TD>
</TR>
<TR>
<TD VALIGN="TOP">DF_SKIP</TD>
<TD VALIGN="TOP">(any)</TD>
<TD>This item is skipped when browsing through items with the arrow keys.
For example, all text items should have this flag set.</TD>
</TR>
<TR>
<TD VALIGN="TOP">DF_SCROLLABLE</TD>
<TD VALIGN="TOP">(any)</TD>
<TD>Set this flag if you want this item to be scrollable in a scroll
region.</TD>
</TR>
<TR>
<TD VALIGN="TOP">DF_TAB_ELLIPSES</TD>
<TD VALIGN="TOP">Request box, pulldown menu</TD>
<TD>Lines the item up on the right side of the dialog, and draws '......'
between the item and its label. This flag is used in the TIOS 'MODE'
dialog, for example. It is the default on AMS 1.xx.</TD>
</TR>
<TR>
<TD VALIGN="TOP">DF_TAB_SPACES</TD>
<TD VALIGN="TOP">Request box, pulldown menu</TD>
<TD>AMS 2.00 or higher: Like DF_TAB_ELLIPSES, but does not draw any
dots.</TD>
</TR>
<TR>
<TD VALIGN="TOP">DF_OWNER_DRAW</TD>
<TD VALIGN="TOP">Text</TD>
<TD>AMS 2.00 or higher: The callback function (see
<A HREF="#DialogNew">DialogNew</A> for more information) is
responsible for drawing this item (which can be text, an image, or
anything else). This can only be done if the dialog was created with
<A HREF="#DialogNew">DialogNew</A> and not
<A HREF="#DialogNewSimple">DialogNewSimple</A>.</TD>
</TR>
<TR>
<TD VALIGN="TOP">DF_POPUP_RADIO</TD>
<TD VALIGN="TOP">Pulldown menu</TD>
<TD>AMS 2.00 or higher: If this flag is set, the item looks like a normal
pulldown menu that you can select, but when you press the right arrow
key, it does not pop up as usual, but returns control to the dialog
callback function. This enables the programmer to do whatever he/she
wants.
For example, in the 'MODE' dialog, setting custom units pops up another
dialog instead of a pulldown menu.</TD>
</TR>
<TR>
<TD VALIGN="TOP">DF_MAX_MENU_WIDTH</TD>
<TD VALIGN="TOP">Main menu</TD>
<TD>AMS 2.00 or higher: Passes
<A HREF="menus.html#MenuBeginFlags">MBF_MAX_MENU_WIDTH</A> to
<A HREF="menus.html#MenuBegin">MenuBegin</A> when the menu is
drawn.</TD>
</TR>
<TR>
<TD VALIGN="TOP">DF_CLR_ON_REDRAW</TD>
<TD VALIGN="TOP">Scroll region</TD>
<TD>Clears the entire visible scroll region when redrawn. If you do not set
this flag, the scroll region will not be cleared before being redrawn,
and you might still see the previously drawn items underneath the new
ones.</TD>
</TR>
</TABLE>
<BR>
<B>Note:</B> If you want your program to work in AMS 1.xx, you cannot pass
D_MENU, D_DYNPOPUP, and D_XFLAGS to this function. Nevertheless, you can
initialize a <A HREF="#DIALOG_STRUCT">DIALOG</A> structure with these
items, and the program will still work on AMS 1.xx.</P>
<P>See also: <A HREF="#DialogDo">DialogDo</A>, <A HREF="#DialogNew">DialogNew</A>, <A HREF="#DIALOG_STRUCT">DIALOG</A></P>
<HR>
<H3><A NAME="DialogAddDynamicPulldown"><U>DialogAddDynamicPulldown</U></A></H3>
<P><A HREF="httigcc.html#minams">AMS 2.00 or higher</A></P>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><A HREF="alloc.html#HANDLE">HANDLE</A> DialogAddDynamicPulldown (<A HREF="alloc.html#HANDLE">HANDLE</A> Handle, <B><A HREF="keywords.html#short">short</A></B> flags, <B><A HREF="keywords.html#short">short</A></B> x, <B><A HREF="keywords.html#short">short</A></B> y, <B><A HREF="keywords.html#const">const</A></B> <B><A HREF="keywords.html#int">char</A></B> *label, <A HREF="#Dialog_GetHandle_t">Dialog_GetHandle_t</A> GetPopup, <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">short</A></B> index);</TD></TR></TABLE></P>
<P><B>Adds a dynamic pulldown menu into a dialog box.</B></P>
<P>DialogAddDynamicPulldown adds a pulldown item to the dialog box associated
with the handle <I>Handle</I> at the position (<I>x</I>,<I>y</I>), where the
coordinates are relative to the top-left corner of the dialog box.
<BR><BR>
When the pulldown is opened, the function passed to the <I>GetPopup</I>
parameter is called (with the identification number of the newly created item
as the value of the <I>ID</I> parameter), and it must return the handle of the
actual popup menu (usually created using
<A HREF="menus.html#PopupNew">PopupNew</A>). See
<A HREF="menus.html">menus.h</A> for more information about creating
popups.
<BR><BR>
An optional label <I>label</I> will appear in front of the request box; an
empty string is used to indicate that no label should be drawn. The parameter
<I>index</I> determines where the result value of executing the pulldown menu
will be stored, and also indicates what the initially selected option will be.
See <A HREF="#DialogDo">DialogDo</A> for information on how and where
the result values are actually stored.
<BR><BR>
The order of item creation is very important, as it automatically gives each
item an identification number (the first created item will get an
identification number of 0, the second one will get 1, and so on). Every
function that creates an item (i.e. every function beginning with
'DialogAdd...') will increase this identification number.
<BR><BR>
The parameter <I>flags</I> can be a combination of the following, defined in
the <A HREF="#DialogFlags">DialogFlags</A> enumeration:
<TABLE BORDER CELLPADDING="3">
<TR>
<TD>DF_SCROLLABLE</TD>
<TD>Set this flag if you want this item to be scrollable in a scroll
region.</TD>
</TR>
<TR>
<TD>DF_SKIP</TD>
<TD>This item is skipped when browsing through items with the arrow keys.</TD>
</TR>
<TR>
<TD>DF_SCREEN_SAVE</TD>
<TD>The dialog code saves the area underneath the dialog box when it is
started, DB_MEMFULL returned if it cannot. If you wish to use this flag,
you must then set it with the first item you created in the dialog box.</TD>
</TR>
<TR>
<TD>DF_TAB_ELLIPSES</TD>
<TD>Lines the item up on the right side of the dialog, and draws '......'
between the item and its label. This flag is used in the TIOS 'MODE'
dialog, for example. It is the default on AMS 1.xx.</TD>
</TR>
<TR>
<TD>DF_TAB_SPACES</TD>
<TD>AMS 2.00 or higher: Like DF_TAB_ELLIPSES, but does not draw any
dots.</TD>
</TR>
<TR>
<TD>DF_POPUP_RADIO</TD>
<TD>AMS 2.00 or higher: If this flag is set, the item looks like a normal
pulldown menu that you can select, but when you press the right arrow
key, it does not pop up as usual, but returns control to the dialog
callback function. This enables the programmer to do whatever he/she
wants.
For example, in the 'MODE' dialog, setting custom units pops up another
dialog instead of a pulldown menu.</TD>
</TR>
</TABLE>
<BR>
DialogAddDynamicPulldown returns <A HREF="alloc.html#H_NULL">H_NULL</A>
in case of an error, may return <A HREF="#DialogMessages">DB_MEMFULL</A>
if you used <A HREF="#DialogFlags">DF_SCREEN_SAVE</A>, else returns
<I>Handle</I>. This routine (as well as all other 'DialogAdd...' routines)
may cause heap compression.
<BR><BR>
DialogAddDynamicPulldown is in fact a macro created for your convenience.
It calls <A HREF="#DialogAdd">DialogAdd</A> with D_DYNPOPUP as the
<I>ItemType</I> parameter.</P>
<HR>
<H3><A NAME="DialogAddDynamicRequest"><U>DialogAddDynamicRequest</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><A HREF="alloc.html#HANDLE">HANDLE</A> DialogAddDynamicRequest (<A HREF="alloc.html#HANDLE">HANDLE</A> Handle, <B><A HREF="keywords.html#short">short</A></B> flags, <B><A HREF="keywords.html#short">short</A></B> x, <B><A HREF="keywords.html#short">short</A></B> y, <B><A HREF="keywords.html#const">const</A></B> <B><A HREF="keywords.html#int">char</A></B> *label, <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">short</A></B> width);</TD></TR></TABLE></P>
<P><B>Adds a request/edit box with a dynamic buffer into a dialog box.</B></P>
<P>DialogAddDynamicRequest adds a request box (i.e. an input line edit box) with a
dynamic buffer to the dialog structure associated with the handle <I>Handle</I>
at the position (<I>x</I>,<I>y</I>), where the coordinates are relative to the
top-left corner of the dialog box. An optional label <I>label</I> will appear
in front of the request box. An empty string, "", is used to indicate no label.
<BR><BR>
Items created with DialogAddDynamicRequest doesn't use the
<I>RequestBuffer</I> array passed to the <A HREF="#Dialog">Dialog</A>
function, so they do not need the <I>offset</I> and <I>MaxLen</I> values like
normal edit items as described in
<A HREF="#DialogAddRequestEx">DialogAddRequestEx</A>. Instead, the
callback function (see <A HREF="#DialogNew">DialogNew</A> for more
information) is called with the first parameter equal to DB_GET_EDIT_HANDLE and
the second parameter equal to the item's identification number. The callback
should then return the handle of an edit buffer of at least <I>width</I> bytes
long. <I>width</I> determines the actual width of the request box (This is very
useful when you need to prevent the user from overstepping a special size such
as file names). It will be such that the widest string made of <I>width</I>
characters may fit into the box. So, the real width of box in pixels will be
<I>width</I>*6, because the widest character 'M' is 6 pixels wide. If you try
to enter a string with more than <I>width</I> characters, the system will
prevent you from doing so. If <I>width</I> is wider than the actually available
width of the dialog box, the request box will be truncated at the edge of the
dialog box.
<BR><BR>
The order of item creation is very important, as it automatically gives each
item an identification number (the first created item will get an
identification number of 0, the second one will get 1, and so on). Every
function that creates an item (i.e. every function beginning with
'DialogAdd...') will increase this identification number.
<BR><BR>
The parameter <I>flags</I> can be a combination of the following, defined in
the <A HREF="#DialogFlags">DialogFlags</A> enumeration:
<TABLE BORDER CELLPADDING="3">
<TR>
<TD>DF_SCROLLABLE</TD>
<TD>Set this flag if you want this item to be scrollable in a scroll
region.</TD>
</TR>
<TR>
<TD>DF_SKIP</TD>
<TD>This item is skipped when browsing through items with the arrow keys.</TD>
</TR>
<TR>
<TD>DF_SCREEN_SAVE</TD>
<TD>The dialog code saves the area underneath the dialog box when it is
started, DB_MEMFULL returned if it cannot. If you wish to use this flag,
you must then set it with the first item you created in the dialog box.</TD>
</TR>
<TR>
<TD>DF_TAB_ELLIPSES</TD>
<TD>Lines the item up on the right side of the dialog, and draws '......'
between the item and its label. This flag is used in the TIOS 'MODE'
dialog, for example. (It is the default on AMS 1.xx. See the note below
for more information.)</TD>
</TR>
<TR>
<TD>DF_TAB_SPACES</TD>
<TD>AMS 2.00 or higher: Like DF_TAB_ELLIPSES, but does not draw any
dots.</TD>
</TR>
</TABLE>
<BR>
<B>Note:</B> On AMS 1.xx, all request boxes in one dialog box will be aligned
according to the request box which has the longest label, except when the label
string finishes with a '`' character (code 96). In such case, the request box
will start immediately after the label string ('`' is a special character,
which will not be displayed). When the label doesn't end with '`', it can be
padded with '<B>.</B>' characters up to the length of the longest label, except
if the label finishes with '<B>:</B>': In that case, the label will be padded
with space characters ('<B>:</B>' will also be displayed).
<BR><BR>
DialogAddDynamicRequest returns <A HREF="alloc.html#H_NULL">H_NULL</A> in case
of an error, may return <A HREF="#DialogMessages">DB_MEMFULL</A> if you
used <A HREF="#DialogFlags">DF_SCREEN_SAVE</A>, else returns
<I>Handle</I>. This routine (as well as all other 'DialogAdd...' routines) may
cause heap compression.
<BR><BR>
DialogAddDynamicRequest is in fact a macro created for your convenience. It
calls <A HREF="#DialogAdd">DialogAdd</A> with D_HEDIT as the
<I>ItemType</I> parameter.</P>
<HR>
<H3><A NAME="DialogAddMenu"><U>DialogAddMenu</U></A></H3>
<P><A HREF="httigcc.html#minams">AMS 2.00 or higher</A></P>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><A HREF="alloc.html#HANDLE">HANDLE</A> DialogAddMenu (<A HREF="alloc.html#HANDLE">HANDLE</A> Handle, <B><A HREF="keywords.html#short">short</A></B> flags, <B><A HREF="keywords.html#short">short</A></B> x, <B><A HREF="keywords.html#short">short</A></B> y, <B><A HREF="keywords.html#void">void</A></B> *Menu, <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">short</A></B> MaxMenuWidth);</TD></TR></TABLE></P>
<P><B>Adds a menu into a dialog box.</B></P>
<P>DialogAddMenu adds the menu <I>Menu</I>, with a maximum width of
<I>MaxMenuWidth</I> (or zero to automatically calculate the width) at the
position (<I>x</I>,<I>y</I>) to the dialog structure associated with the handle
<I>Handle</I>, where the coordinates are relative to the top-left corner of the
dialog box.
<BR><BR>
A menu item is defined by a pointer <I>Menu</I> to a toolbar menu structure
created statically (i.e. you must include a pre-filled static menu in your
source code) or dynamically with <A HREF="menus.html#MenuNew">MenuNew</A>
(in this case the caller must ensure the structure remains locked while in use
in the dialog box, i.e. use <A HREF="alloc.html#HLock">HLock</A> in the
same way as for <A HREF="menus.html#MenuBegin">MenuBegin</A>). The menu
is drawn by an internal call to
<A HREF="menus.html#MenuBegin">MenuBegin</A>. When a menu key is pressed,
the callback's (see <A HREF="#DialogNew">DialogNew</A> for more
information) <I>Message</I> value will be the item's identification number and
<I>Value</I> will be passed the menu handle returned from
<A HREF="menus.html#MenuBegin">MenuBegin</A> in the high word and the key
code in the low word. You can specify a maximum width for your menu in
<I>MaxMenuWidth</I> or zero if you want it to be automatically calculated. Each
dialog box can have at most one menu. The creation of menus is explained in the
header file <A HREF="menus.html">menus.h</A>. Note that if you want a
menu, you must write a callback function, else you will not be able to do
anything but dispaying it!
<BR><BR>
The order of item creation is very important, as it automatically gives each
item an identification number (the first created item will get an
identification number of 0, the second one will get 1, and so on). Every
function that creates an item (i.e. every function beginning with
'DialogAdd...') will increase this identification number.
<BR><BR>
The parameter <I>flags</I> can be a combination of the following, defined in
the <A HREF="#DialogFlags">DialogFlags</A> enumeration:
<TABLE BORDER CELLPADDING="3">
<TR>
<TD>DF_SCREEN_SAVE</TD>
<TD>The dialog code saves the area underneath the dialog box when it is
started, DB_MEMFULL returned if it cannot. If you wish to use this flag,
you must then set it with the first item you created in the dialog box.</TD>
</TR>
<TR>
<TD>DF_MAX_MENU_WIDTH</TD>
<TD>AMS 2.00 or higher: Passes
<A HREF="menus.html#MenuBeginFlags">MBF_MAX_MENU_WIDTH</A> to
<A HREF="menus.html#MenuBegin">MenuBegin</A> when the menu is
drawn.</TD>
</TR>
</TABLE>
<BR><BR>
DialogAddMenu returns <A HREF="alloc.html#H_NULL">H_NULL</A> in case
of an error, may return <A HREF="#DialogMessages">DB_MEMFULL</A> if you
used <A HREF="#DialogFlags">DF_SCREEN_SAVE</A>, else returns
<I>Handle</I>. This routine (as well as all other 'DialogAdd...' routines) may
cause heap compression.
<BR><BR>
DialogAddMenu is in fact a macro created for your convenience. It calls
<A HREF="#DialogAdd">DialogAdd</A> with D_MENU as the <I>ItemType</I>
parameter.</P>
<HR>
<H3><A NAME="DialogAddPulldown"><U>DialogAddPulldown</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><A HREF="alloc.html#HANDLE">HANDLE</A> DialogAddPulldown (<A HREF="alloc.html#HANDLE">HANDLE</A> Handle, <B><A HREF="keywords.html#short">short</A></B> x, <B><A HREF="keywords.html#short">short</A></B> y, <B><A HREF="keywords.html#const">const</A></B> <B><A HREF="keywords.html#int">char</A></B> *prompt, <A HREF="alloc.html#HANDLE">HANDLE</A> MenuHandle, <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">short</A></B> index);</TD></TR></TABLE></P>
<P><B>Adds a pulldown/popup menu into a dialog box.</B></P>
<P>DialogAddPulldown works exactly as
<A HREF="#DialogAddPulldownEx">DialogAddPulldownEx</A>, but doesn't have
the <I>flags</I> parameter available. This routine is in fact a macro using
<A HREF="#DialogAdd">DialogAdd</A> with D_HPOPUP passed as a command and
zero passed as the flags. All the parameters are explained in
<A HREF="#DialogAddPulldownEx">DialogAddPulldownEx</A>.</P>
<HR>
<H3><A NAME="DialogAddPulldownEx"><U>DialogAddPulldownEx</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><A HREF="alloc.html#HANDLE">HANDLE</A> DialogAddPulldownEx (<A HREF="alloc.html#HANDLE">HANDLE</A> Handle, <B><A HREF="keywords.html#short">short</A></B> flags, <B><A HREF="keywords.html#short">short</A></B> x, <B><A HREF="keywords.html#short">short</A></B> y, <B><A HREF="keywords.html#const">const</A></B> <B><A HREF="keywords.html#int">char</A></B> *label, <A HREF="alloc.html#HANDLE">HANDLE</A> PopupMenu, <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">short</A></B> index);</TD></TR></TABLE></P>
<P><B>Adds a pulldown/popup menu into a dialog box. Extended version.</B></P>
<P>DialogAddPulldownEx adds the pulldown menu <I>PopupMenu</I> to the dialog
structure associated with the handle <I>Handle</I> at the position
(<I>x</I>,<I>y</I>), where the coordinates are relative to the top-left corner
of the dialog box.
<BR><BR>
<I>label</I> is the label which will appear in front of the popup menu (or ""
if you don't want any name), and <I>MenuHandle</I> is the handle of the
associated menu which needs to be created using the
<A HREF="menus.html#PopupNew">PopupNew</A> function (the same functions
are used for creating pulldown and popup menus). See
<A HREF="menus.html">menus.h</A> for more info about creating popups.
The text must fit into one line of the dialog box.
<BR><BR>
The parameter <I>index</I> determines where the result value of executing the
pulldown menu will be stored, and also indicates what the initially selected
option will be. See <A HREF="#DialogDo">DialogDo</A> for information on
how and where the result values are actually stored.
<BR><BR>
The order of item creation is very important, as it automatically gives each
item an identification number (the first created item will get an
identification number of 0, the second one will get 1, and so on). Every
function that creates an item (i.e. every function beginning with
'DialogAdd...') will increase this identification number.
<BR><BR>
The parameter <I>flags</I> can be a combination of the following, defined in
the <A HREF="#DialogFlags">DialogFlags</A> enumeration:
<TABLE BORDER CELLPADDING="3">
<TR>
<TD>DF_SCROLLABLE</TD>
<TD>Set this flag if you want this item to be scrollable in a scroll
region.</TD>
</TR>
<TR>
<TD>DF_SKIP</TD>
<TD>This item is skipped when browsing through items with the arrow keys.</TD>
</TR>
<TR>
<TD>DF_SCREEN_SAVE</TD>
<TD>The dialog code saves the area underneath the dialog box when it is
started, DB_MEMFULL returned if it cannot. If you wish to use this flag,
you must then set it with the first item you created in the dialog box.</TD>
</TR>
<TR>
<TD>DF_TAB_ELLIPSES</TD>
<TD>Lines the item up on the right side of the dialog, and draws '......'
between the item and its label. This flag is used in the TIOS 'MODE'
dialog, for example. It is the default on AMS 1.xx.</TD>
</TR>
<TR>
<TD>DF_TAB_SPACES</TD>
<TD>AMS 2.00 or higher: Like DF_TAB_ELLIPSES, but does not draw any
dots.</TD>
</TR>
<TR>
<TD>DF_POPUP_RADIO</TD>
<TD>AMS 2.00 or higher: If this flag is set, the item looks like a normal
pulldown menu that you can select, but when you press the right arrow
key, it does not pop up as usual, but returns control to the dialog
callback function. This enables the programmer to do whatever he/she
wants.
For example, in the 'MODE' dialog, setting custom units pops up another
dialog instead of a pulldown menu.</TD>
</TR>
</TABLE>
<BR>
DialogAddPulldownEx returns <A HREF="alloc.html#H_NULL">H_NULL</A> in case
of an error, may return <A HREF="#DialogMessages">DB_MEMFULL</A> if you
used <A HREF="#DialogFlags">DF_SCREEN_SAVE</A>, else returns
<I>Handle</I>. This routine (as well as all other 'DialogAdd...' routines) may
cause heap compression.
<BR><BR>
DialogAddPulldownEx is in fact a macro created for your convenience. It calls
<A HREF="#DialogAdd">DialogAdd</A> with D_HPOPUP as the <I>ItemType</I>
parameter. Note that DialogAddPulldownEx is the same macro as
<A HREF="#DialogAddPulldown">DialogAddPulldown</A> except for the
parameter <I>flags</I> which is always set to zero in
<A HREF="#DialogAddPulldown">DialogAddPulldown</A>.</P>
<HR>
<H3><A NAME="DialogAddRequest"><U>DialogAddRequest</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><A HREF="alloc.html#HANDLE">HANDLE</A> DialogAddRequest (<A HREF="alloc.html#HANDLE">HANDLE</A> Handle, <B><A HREF="keywords.html#short">short</A></B> x, <B><A HREF="keywords.html#short">short</A></B> y, <B><A HREF="keywords.html#const">const</A></B> <B><A HREF="keywords.html#int">char</A></B> *prompt, <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">short</A></B> offset, <B><A HREF="keywords.html#short">short</A></B> MaxLen, <B><A HREF="keywords.html#short">short</A></B> width);</TD></TR></TABLE></P>
<P><B>Adds a request/edit box into a dialog box.</B></P>
<P>DialogAddRequest works exactly as
<A HREF="#DialogAddRequestEx">DialogAddRequestEx</A>, but doesn't have
the <I>flags</I> parameter available. This routine is in fact a macro using
<A HREF="#DialogAdd">DialogAdd</A> with D_EDIT_FIELD passed as a
command and zero passed as the flags. All the parameters are explained in
<A HREF="#DialogAddRequestEx">DialogAddRequestEx</A>.</P>
<HR>
<H3><A NAME="DialogAddRequestEx"><U>DialogAddRequestEx</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><A HREF="alloc.html#HANDLE">HANDLE</A> DialogAddRequestEx (<A HREF="alloc.html#HANDLE">HANDLE</A> Handle, <B><A HREF="keywords.html#short">short</A></B> flags, <B><A HREF="keywords.html#short">short</A></B> x, <B><A HREF="keywords.html#short">short</A></B> y, <B><A HREF="keywords.html#const">const</A></B> <B><A HREF="keywords.html#int">char</A></B> *label, <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">short</A></B> offset, <B><A HREF="keywords.html#short">short</A></B> MaxLen, <B><A HREF="keywords.html#short">short</A></B> width);</TD></TR></TABLE></P>
<P><B>Adds a request/edit box into a dialog box. Extended version.</B></P>
<P>DialogAddRequestEx adds a request box (i.e. an input line edit box) to the
dialog structure associated with the handle <I>Handle</I> at the position
(<I>x</I>,<I>y</I>), where the coordinates are relative to the top-left corner
of the dialog box. An optional label <I>label</I> will appear in front of the
request box. An empty string, "", is used to indicate no label.
<BR><BR>
The maximal number of characters which may be entered is determined by the
parameter <I>MaxLen</I> (<I>MaxLen</I> must at most have the size of the
<I>RequestBuffer</I> given to <A HREF="#DialogDo">DialogDo</A>), and
<I>width</I> determines the actual display width of the request box
(<I>MaxLen</I> can be very usefull when you need to prevent the user from
overstepping a special size such as file names). It will be such that the
widest string made of <I>width</I> characters may fit into the box. So, the
real display width of box in pixels will be <I>width</I>*6, because the widest
character 'M' is 6 pixels wide. If you try to enter a string with more than
<I>width</I> characters, the content of the request box will scroll, and if you
try to have a string longer than <I>MaxLen</I>, the system will prevent you
from doing so. If <I>width</I> is wider than the actually available width of
the dialog box, the request box will be truncated at the edge of the dialog
box.
<BR><BR>
The parameter <I>offset</I> determines what will be the initial content of the
request box, and where the entered characters will be stored. See
<A HREF="#DialogDo">DialogDo</A> for information on how and where the
entered characters are actually stored.
<BR><BR>
The order of item creation is very important, as it automatically gives each
item an identification number (the first created item will get an
identification number of 0, the second one will get 1, and so on). Every
function that creates an item (i.e. every function beginning with
'DialogAdd...') will increase this identification number.
<BR><BR>
The parameter <I>flags</I> can be a combination of the following, defined in
the <A HREF="#DialogFlags">DialogFlags</A> enumeration:
<TABLE BORDER CELLPADDING="3">
<TR>
<TD>DF_SCROLLABLE</TD>
<TD>Set this flag if you want this item to be scrollable in a scroll
region.</TD>
</TR>
<TR>
<TD>DF_SKIP</TD>
<TD>This item is skipped when browsing through items with the arrow keys.</TD>
</TR>
<TR>
<TD>DF_SCREEN_SAVE</TD>
<TD>The dialog code saves the area underneath the dialog box when it is
started, DB_MEMFULL returned if it cannot. If you wish to use this flag,
you must then set it with the first item you created in the dialog box.</TD>
</TR>
<TR>
<TD>DF_TAB_ELLIPSES</TD>
<TD>Lines the item up on the right side of the dialog, and draws '......'
between the item and its label. This flag is used in the TIOS 'MODE'
dialog, for example. (It is the default on AMS 1.xx. See the note below
for more information.)</TD>
</TR>
<TR>
<TD>DF_TAB_SPACES</TD>
<TD>AMS 2.00 or higher: Like DF_TAB_ELLIPSES, but does not draw any
dots.</TD>
</TR>
</TABLE>
<BR>
<B>Note:</B> On AMS 1.xx, all request boxes in one dialog box will be aligned
according to the request box which has the longest label, except when the label
string finishes with a '`' character (code 96). In such case, the request box
will start immediately after the label string ('`' is a special character,
which will not be displayed). When the label doesn't end with '`', it can be
padded with '<B>.</B>' characters up to the length of the longest label, except
if the label finishes with '<B>:</B>': In that case, the label will be padded
with space characters ('<B>:</B>' will also be displayed).
<BR><BR>
DialogAddRequestEx returns <A HREF="alloc.html#H_NULL">H_NULL</A> in case
of an error, may return <A HREF="#DialogMessages">DB_MEMFULL</A> if you
used <A HREF="#DialogFlags">DF_SCREEN_SAVE</A>, else returns
<I>Handle</I>. This routine (as well as all other 'DialogAdd...' routines) may
cause heap compression.
<BR><BR>
DialogAddRequestEx is in fact a macro created for your convenience. It calls
<A HREF="#DialogAdd">DialogAdd</A> with D_EDIT_FIELD as the
<I>ItemType</I> parameter. Note that DialogAddRequestEx is the same macro as
<A HREF="#DialogAddRequest">DialogAddRequest</A> except for the parameter
<I>flags</I> which is always set to zero in
<A HREF="#DialogAddRequest">DialogAddRequest</A>.</P>
<HR>
<H3><A NAME="DialogAddScrollRegion"><U>DialogAddScrollRegion</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><A HREF="alloc.html#HANDLE">HANDLE</A> DialogAddScrollRegion (<A HREF="alloc.html#HANDLE">HANDLE</A> Handle, <B><A HREF="keywords.html#short">short</A></B> flags, <B><A HREF="keywords.html#short">short</A></B> x, <B><A HREF="keywords.html#short">short</A></B> y, <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">short</A></B> x1, <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">short</A></B> y1, <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">short</A></B> FirstItem, <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">short</A></B> LastItem, <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">short</A></B> NumDspItems, <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">short</A></B> TotNumItems, <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">short</A></B> ItemHeight);</TD></TR></TABLE></P>
<P><B>Adds a rectangular item-scrolling region to a dialog box.</B></P>
<P>DialogAddScrollRegion adds a rectangular item-scrolling region to the dialog
structure associated with the handle <I>Handle</I> from the
(<I>x</I>, <I>y</I>) position to the (<I>x1</I>, <I>y1</I>) position, where
all coordinates are relative to the top-left corner of the dialog box.
<BR><BR>
A scroll region defines a group of items that will scroll as the user moves
through the items. The identification number of the first scrollable should
be set in <I>FirstItem</I> and the last scrollable item in <I>LastItem</I>.
<I>NumDspItems</I> defines the number of items that are displayed at one time.
The total number of scrollable item should be set in <I>TotNumItems</I> and
the height of each item in <I>ItemHeight</I>. Every scrollable item must be
defined contiguously and have the DF_SCROLLABLE flag set and must not be of
MENU, HEADER or XFLAGS type. The coordinates of the scrollable items are
relative to the dialog box except that they may extend beyond the bottom
coordinate of the dialog box. They are defined assuming a virtual scroll
region.
<BR><BR>
It's very easy to cause display bugs using this function (of course, that
won't crash your calculator, but the dialog can easily become ugly), so here
is a method you can use to avoid those bugs: First, the standard item height
is the height of the biggest item (often the EDIT item which is 10 pixel high),
so the minimum value in <I>ItemHeight</I> should be 10 in most cases. Then, to
avoid any display bugs, the <I>y</I> axis should be the y value of your first
displayed item - 2 and <I>y1</I> axis should be the y value of your last
displayed item + 8. I.e. if you wish to scroll 8 items and only display items
3 by 3 (but please use the available screen space: don't just restrict the
items displayed at a time to 3 just because everyone else does it), and the
first scrollable item is item number 4 (the last displayed item at the
beginning is therefore item 6), the calculation should be:
<I>y</I>=(item 4 y axis)-2 and <I>y1</I>=(item 6 y axis)+8). The difference
<I>x1</I>-<I>x</I> should also be greater than the width of the largest item
(else it will result in display bugs). I don't really understand the utility
of such a <I>TotNumItems</I> parameter as it should always be equal to
<I>LastItem</I>-<I>FirstItem</I>+1. The flag DF_CLR_ON_REDRAW is very useful
and should be set in most cases (see below).
<BR><BR>
<B>Note:</B> If you use a SCROLL_REGION, it must be the first item defined in
the dialog box. A dialog box can therefore have at most one scroll region.
<BR><BR>
The order of item creation is very important, as it automatically gives each
item an identification number (the first created item will get an
identification number of 0, the second one will get 1, and so on). Every
function that creates an item (i.e. every function beginning with
'DialogAdd...') will increase this identification number.
<BR><BR>
The parameter <I>flags</I> can be a combination of the following, defined in
the <A HREF="#DialogFlags">DialogFlags</A> enumeration:
<TABLE BORDER CELLPADDING="3">
<TR>
<TD>DF_SKIP</TD>
<TD>This item is skipped when browsing through items with the arrow keys.</TD>
</TR>
<TR>
<TD>DF_SCREEN_SAVE</TD>
<TD>The dialog code saves the area underneath the dialog box when it is
started, DB_MEMFULL returned if it cannot. If you wish to use this flag,
you must then set it with the first item you created in the dialog box.</TD>
</TR>
<TR>
<TD>DF_CLR_ON_REDRAW</TD>
<TD>Clears the entire visible scroll region when redrawn. If you do not set
this flag, the scroll region will not be cleared before being redrawn,
and you might still see the previously drawn items underneath the new
ones.</TD>
</TR>
</TABLE>
<BR><BR>
DialogAddScrollRegion returns <A HREF="alloc.html#H_NULL">H_NULL</A> in case
of an error, may return <A HREF="#DialogMessages">DB_MEMFULL</A> if you
used <A HREF="#DialogFlags">DF_SCREEN_SAVE</A>, else returns
<I>Handle</I>. This routine (as well as all other 'DialogAdd...' routines) may
cause heap compression.
<BR><BR>
DialogAddScrollRegion is in fact a macro created for your convenience. It calls
<A HREF="#DialogAdd">DialogAdd</A> with D_SCROLL_REGION as the
<I>ItemType</I> parameter.</P>
<HR>
<H3><A NAME="DialogAddStaticPulldown"><U>DialogAddStaticPulldown</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><A HREF="alloc.html#HANDLE">HANDLE</A> DialogAddStaticPulldown (<A HREF="alloc.html#HANDLE">HANDLE</A> Handle, <B><A HREF="keywords.html#short">short</A></B> flags, <B><A HREF="keywords.html#short">short</A></B> x, <B><A HREF="keywords.html#short">short</A></B> y, <B><A HREF="keywords.html#const">const</A></B> <B><A HREF="keywords.html#int">char</A></B> *label, <B><A HREF="keywords.html#void">void</A></B> *Popup, <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">short</A></B> index);</TD></TR></TABLE></P>
<P><B>Adds a static pulldown/popup menu into a dialog box.</B></P>
<P>DialogAddStaticPulldown uses the pointer <I>Popup</I> to a static pre-filled
popup menu structure (popup menus and dialog pulldowns are in fact the same
structure) and adds this pulldown menu to the dialog structure associated with
the handle <I>Handle</I> at the position (<I>x</I>,<I>y</I>), where the
coordinates are relative to the top-left corner of the dialog box.
<BR><BR>
<I>label</I> is the label which will appear in front of the popup menu (or ""
if you don't want any name), and <I>Popup</I> is a prefilled static
<A HREF="menus.html#MenuPopup">popup structure</A> (i.e. you must write
this popup in your source code; for dynamic pop-ups use
<A HREF="#DialogAddPulldownEx">DialogAddPulldownEx</A>) of the
associated menu. See <A HREF="menus.html">menus.h</A> for more info about
creating static popups. The text must fit into one line of the dialog box.
<BR><BR>
The parameter <I>index</I> determines where the result value of executing the
pulldown menu will be stored, and also indicates what the initially selected
option will be. See <A HREF="#DialogDo">DialogDo</A> for information on
how and where the result values are actually stored.
<BR><BR>
The order of item creation is very important, as it automatically gives each
item an identification number (the first created item will get an
identification number of 0, the second one will get 1, and so on). Every
function that creates an item (i.e. every function beginning with
'DialogAdd...') will increase this identification number.
<BR><BR>
DialogAddStaticPulldown works like
<A HREF="#DialogAddPulldownEx">DialogAddPulldownEx</A>, but only accepts
a static pre-filled dialog <I>Popup</I> instead of a handle.
<BR><BR>
The parameter <I>flags</I> can be a combination of the following, defined in
the <A HREF="#DialogFlags">DialogFlags</A> enumeration:
<TABLE BORDER CELLPADDING="3">
<TR>
<TD>DF_SCROLLABLE</TD>
<TD>Set this flag if you want this item to be scrollable in a scroll
region.</TD>
</TR>
<TR>
<TD>DF_SKIP</TD>
<TD>This item is skipped when browsing through items with the arrow keys.</TD>
</TR>
<TR>
<TD>DF_SCREEN_SAVE</TD>
<TD>The dialog code saves the area underneath the dialog box when it is
started, DB_MEMFULL returned if it cannot. If you wish to use this flag,
you must then set it with the first item you created in the dialog box.</TD>
</TR>
<TR>
<TD>DF_TAB_ELLIPSES</TD>
<TD>Lines the item up on the right side of the dialog, and draws '......'
between the item and its label. This flag is used in the TIOS 'MODE'
dialog, for example. It is the default on AMS 1.xx.</TD>
</TR>
<TR>
<TD>DF_TAB_SPACES</TD>
<TD>AMS 2.00 or higher: Like DF_TAB_ELLIPSES, but does not draw any
dots.</TD>
</TR>
<TR>
<TD>DF_POPUP_RADIO</TD>
<TD>AMS 2.00 or higher: If this flag is set, the item looks like a normal
pulldown menu that you can select, but when you press the right arrow
key, it does not pop up as usual, but returns control to the dialog
callback function. This enables the programmer to do whatever he/she
wants.
For example, in the 'MODE' dialog, setting custom units pops up another
dialog instead of a pulldown menu.</TD>
</TR>
</TABLE>
<BR>
DialogAddStaticPulldown returns <A HREF="alloc.html#H_NULL">H_NULL</A> in case
of an error, may return <A HREF="#DialogMessages">DB_MEMFULL</A> if you
used <A HREF="#DialogFlags">DF_SCREEN_SAVE</A>, else returns
<I>Handle</I>. This routine (as well as all other 'DialogAdd...' routines) may
cause heap compression.
<BR><BR>
DialogAddStaticPulldown is in fact a macro created for your convenience. It
calls <A HREF="#DialogAdd">DialogAdd</A> with D_POPUP as the
<I>ItemType</I> parameter.</P>
<HR>
<H3><A NAME="DialogAddText"><U>DialogAddText</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><A HREF="alloc.html#HANDLE">HANDLE</A> DialogAddText (<A HREF="alloc.html#HANDLE">HANDLE</A> Handle, <B><A HREF="keywords.html#short">short</A></B> x, <B><A HREF="keywords.html#short">short</A></B> y, <B><A HREF="keywords.html#const">const</A></B> <B><A HREF="keywords.html#int">char</A></B> *text);</TD></TR></TABLE></P>
<P><B>Adds a text into a dialog box.</B></P>
<P>DialogAddText works exactly as <A HREF="#DialogAddTextEx">DialogAddTextEx</A>,
but doesn't have the <I>flags</I> parameter available. This routine is in fact a
macro using <A HREF="#DialogAdd">DialogAdd</A> with D_TEXT passed as a
command and zero passed as the flags. All the parameters are explained in
<A HREF="#DialogAddTextEx">DialogAddTextEx</A>.</P>
<HR>
<H3><A NAME="DialogAddTextEx"><U>DialogAddTextEx</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><A HREF="alloc.html#HANDLE">HANDLE</A> DialogAddTextEx(<A HREF="alloc.html#HANDLE">HANDLE</A> Handle, <B><A HREF="keywords.html#short">short</A></B> flags, <B><A HREF="keywords.html#short">short</A></B> x, <B><A HREF="keywords.html#short">short</A></B> y, <B><A HREF="keywords.html#const">const</A></B> <B><A HREF="keywords.html#int">char</A></B> *text);</TD></TR></TABLE></P>
<P><B>Adds a text, an image, or a custom item into a dialog box.</B></P>
<P>DialogAddTextEx gives two possibilities:
<BR><BR>
The first one (if, as is the case of
<A HREF="#DialogAddText">DialogAddText</A>, the <I>flags</I> parameter
doesn't contain the DF_OWNER_DRAW flag) is to add the text <I>text</I> to the
dialog structure associated with the handle <I>Handle</I> at the position
(<I>x</I>, <I>y</I>), where the coordinates are relative to the top-left corner
of the dialog box.
<BR><BR>
The second possibility (when the <I>flags</I> parameter contains the
DF_OWNER_DRAW flag) is that DialogAddText can add any kind of item to the
dialog structure associated with the handle <I>Handle</I> at the position
(<I>x</I>, <I>y</I>), where the coordinates are relative to the top-left corner
of the dialog box. (This position can later be ignored so owner draw items will
not necessarily have to stick to this position.) You can create every kind of
item you wish with this function (such as text, buttons, bitmaps...) as far as
you create a callback function (see <A HREF="#DialogNew">DialogNew</A>
for more details on the <I>CallBack</I> function). See the DF_OWNER_DRAW flag
below for more information.
<BR><BR>
The order of item creation is very important, as it automatically gives each
item an identification number (the first created item will get an
identification number of 0, the second one will get 1, and so on). Every
function that creates an item (i.e. every function beginning with
'DialogAdd...') will increase this identification number.
<BR><BR>
The parameter <I>flags</I> can be a combination of the following, defined in
the <A HREF="#DialogFlags">DialogFlags</A> enumeration (DF_OWNER_DRAW
is very important as it can increase the numbers of possible items in dialogs):
<TABLE BORDER CELLPADDING="3">
<TR>
<TD>DF_SCROLLABLE</TD>
<TD>Set this flag if you want this item to be scrollable in a scroll
region.</TD>
</TR>
<TR>
<TD>DF_SCREEN_SAVE</TD>
<TD>The dialog code saves the area underneath the dialog box when it is
started, DB_MEMFULL returned if it cannot. If you wish to use this flag,
you must then set it with the first item you created in the dialog box.</TD>
</TR>
<TR>
<TD>DF_OWNER_DRAW</TD>
<TD>AMS 2.00 or higher: The callback function (see
<A HREF="#DialogNew">DialogNew</A> for more information) is
responsible for drawing this item (which can be text, an image, or
anything else). The parameters <I>text</I>, <I>x</I> and <I>y</I> will in
this case be ignored. This can only be done if the dialog was created with
<A HREF="#DialogNew">DialogNew</A> and not
<A HREF="#DialogNewSimple">DialogNewSimple</A>.<BR><BR>
If the DF_OWNER_DRAW flag is set, then the callback is passed the item
identification number and a pointer to an
<A HREF="#OWNER_DRAW_STRUCT">OWNER_DRAW_STRUCT</A> structure.
The first value <I>Item</I> in this structure is a direct pointer to the
<A HREF="#DIALOG_ITEM">DIALOG_ITEM</A> structure for the item to
be drawn. The second value <I>pW</I> is a pointer to the
<A HREF="wingraph.html#WINDOW">WINDOW</A> structure for the dialog box.
Using this pointer, the callback can draw anything and anywhere to the
dialog box (all clipped to the dialog box window).</TD>
</TR>
</TABLE>
<BR><BR>
<B>Note:</B> By default, the DF_SKIP flag is set whenever you try to create
text or owner draw items so you will not be able to focus on them.
<BR><BR>
DialogAddTextEx returns <A HREF="alloc.html#H_NULL">H_NULL</A> in case
of an error, may return <A HREF="#DialogMessages">DB_MEMFULL</A> if you
used <A HREF="#DialogFlags">DF_SCREEN_SAVE</A>, else returns
<I>Handle</I>. This routine (as well as all other 'DialogAdd...' routines) may
cause heap compression.
<BR><BR>
DialogAddTextEx is in fact a macro created for your convenience. It calls
<A HREF="#DialogAdd">DialogAdd</A> with D_TEXT as the <I>ItemType</I>
parameter. Note that DialogAddTextEx is the same macro as
<A HREF="#DialogAddText">DialogAddText</A> except for the parameter
<I>flags</I> which is always set to zero in
<A HREF="#DialogAddText">DialogAddText</A>.</P>
<HR>
<H3><A NAME="DialogAddTitle"><U>DialogAddTitle</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><A HREF="alloc.html#HANDLE">HANDLE</A> DialogAddTitle (<A HREF="alloc.html#HANDLE">HANDLE</A> Handle, <B><A HREF="keywords.html#const">const</A></B> <B><A HREF="keywords.html#int">char</A></B> *title, <B><A HREF="keywords.html#short">short</A></B> left_button, <B><A HREF="keywords.html#short">short</A></B> right_button);</TD></TR></TABLE></P>
<P><B>Adds a title bar and up to two buttons into a dialog box.</B></P>
<P>DialogAddTitle works exactly as
<A HREF="#DialogAddTitleEx">DialogAddTitleEx</A>, but doesn't have the
<I>flags</I> parameter available. This routine is in fact a macro using
<A HREF="#DialogAdd">DialogAdd</A> with D_HEADER passed as a command
and zero passed as the flags. All the parameters are explained in
<A HREF="#DialogAddTitleEx">DialogAddTitleEx</A>.</P>
<HR>
<H3><A NAME="DialogAddTitleEx"><U>DialogAddTitleEx</U></A></H3>
<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><A HREF="alloc.html#HANDLE">HANDLE</A> DialogAddTitleEx (<A HREF="alloc.html#HANDLE">HANDLE</A> Handle, <B><A HREF="keywords.html#short">short</A></B> flags, <B><A HREF="keywords.html#const">const</A></B> <B><A HREF="keywords.html#int">char</A></B> *title, <B><A HREF="keywords.html#short">short</A></B> left_button, <B><A HREF="keywords.html#short">short</A></B> right_button);</TD></TR></TABLE></P>
<P><B>Adds a title/header bar and up to two buttons into a dialog box. Extended version.</B></P>
<P>DialogAddTitleEx adds a title/header bar with the text <I>title</I> and up to
two buttons to the dialog structure associated with the handle <I>Handle</I>.
<BR><BR>
The parameters <I>left_button</I> and <I>right_button</I> determine the type of
the left and right buttons which eventually will appear at the bottom of the
dialog box (by giving <A HREF="#Buttons">BT_NONE</A> as the parameter,
you can skip adding a button). The set of possible buttons is very limited. See
<A HREF="#DlgMessage">DlgMessage</A> for information about possible
types. If you wish to have buttons without having a title bar, then you must
use an owner draw item (see
<A HREF="#DialogAddTextEx">DialogAddTextEx</A> and the explanation on
owner draw items given with <A HREF="#DialogNew">DialogNew</A> for more
information).
<BR><BR>
The parameter <I>flags</I> can be zero or DF_SCREEN_SAVE if you wish the dialog
code to save the area underneath the dialog box when it is started, DB_MEMFULL
is returned if it cannot. Note that if you use this flag, the title item must
be the first one to be created. These flags are defined in the
<A HREF="#DialogFlags">DialogFlags</A> enumeration.
<BR><BR>
The order of item creation is very important, as it automatically gives each
item an identification number (the first created item will get an
identification number of 0, the second one will get 1, and so on). Every
function that creates an item (i.e. every function beginning with
'DialogAdd...') will increase this identification number.
<BR><BR>
DialogAddTitleEx returns <A HREF="alloc.html#H_NULL">H_NULL</A> in case
of an error, may return <A HREF="#DialogMessages">DB_MEMFULL</A> if you
used <A HREF="#DialogFlags">DF_SCREEN_SAVE</A>, else returns
<I>Handle</I>. This routine (as well as all other 'DialogAdd...' routines) may
cause heap compression.
<BR><BR>
DialogAddTitleEx is in fact a macro created for your convenience. It calls
<A HREF="#DialogAdd">DialogAdd</A> with D_HEADER as the <I>ItemType</I>
parameter. Note that DialogAddTitleEx is the same macro as