
                       The programming docs for
                               WDIALOG

                             Version 2.00
                             4th May 1998
                                 by
                        Sven & Wilfried Behne

				English translation: Peter West
						 April 99

Contents
========

 1 Intentions, conditions, ovations
   1.1 Installation
   1.2 Conditions
   1.3 Exclusion of liability
   1.4 Disclaimer

 2 WDIALOG Programmer's Guide

   2.1 Data types and structures
   2.2 How do I recognise WDIALOG?
   2.3 Window dialogs
       2.3.1 Calling procedure for window dialogs
       2.3.2 WINDOW DIALOG - CREATE (AES 160)
       2.3.3 WINDOW DIALOG - OPEN (AES 161)
       2.3.4 WINDOW DIALOG - CLOSE (AES 162)
       2.3.5 WINDOW DIALOG - DELETE (AES 163)
       2.3.6 WINDOW DIALOG - GET OBJECT TREE (AES 164, 0)
       2.3.7 WINDOW DIALOG - GET EDIT OBJECT (AES 164, 1)
       2.3.8 WINDOW DIALOG - GET USERDATA (AES 164, 2)
       2.3.9 WINDOW DIALOG - GET WINDOW HANDLE (AES 164, 3)
       2.3.10 WINDOW DIALOG - SET EDIT OBJECT (AES 165, 0)
       2.3.11 WINDOW DIALOG - SET TREE (AES 165, 1)
       2.3.12 WINDOW DIALOG - SET SIZE (AES 165, 2)
       2.3.13 WINDOW DIALOG - ICONIFY (AES 165, 3)
       2.3.14 WINDOW DIALOG - UNICONIFY (AES 165, 4)
       2.3.15 WINDOW DIALOG - EVENT (AES 166)
       2.3.16 WINDOW DIALOG - REDRAW (AES 167)
   2.4 List boxes
       2.4.1 Calling procedure for modal dialogs
       2.4.2 LIST BOX - CREATE (AES 170)
       2.4.3 LIST BOX - UPDATE (AES 171)
       2.4.4 LIST BOX - DO (AES 172)
       2.4.5 LIST BOX - DELETE (AES 173)
       2.4.6 LIST BOX - COUNT ITEMS (AES 174, 0)
       2.4.7 LIST BOX - GET TREE (AES 174, 1)
       2.4.8 LIST BOX - GET NUMBER OF VISIBLE ITEMS, SLIDER A (AES 174, 2)
       2.4.9 LIST BOX - GET USER DATA (AES 174, 3)
       2.4.10 LIST BOX - GET FIRST VISIBLE ITEM, SLIDER A (AES 174, 4)
       2.4.11 LIST BOX - GET INDEX of SELECTED ITEM (AES 174, 5)
       2.4.12 LIST BOX - GET ITEMS (AES 174, 6)
       2.4.13 LIST BOX - GET ITEM (AES 174, 7)
       2.4.14 LIST BOX - GET SELECTED ITEM (AES 174, 8)
       2.4.15 LIST BOX - GET ITEM INDEX (AES 174, 9)
       2.4.16 LIST BOX - GET NUMBER OF VISIBLE ITEMS, SLIDER B (AES 174, 10)
       2.4.17 LIST BOX - GET NUMBER OF ITEMS, SLIDER B (AES 174, 11)
       2.4.18 LIST BOX - GET FIRST VISIBLE ITEM, SLIDER B (AES 174, 12)
       2.4.19 LIST BOX - SET SLIDER A (AES 175, 0)
       2.4.20 LIST BOX - SET NEW ITEM LIST (AES 175, 1)
       2.4.21 LIST BOX - FREE ITEMS (AES 175, 2)
       2.4.22 LIST BOX - FREE ITEM LIST (AES 175, 3)
       2.4.23 LIST BOX - SCROLL TO, SLIDER A (AES 175, 4)
       2.4.24 LIST BOX - SET SLIDER B (AES 175, 5)
       2.4.25 LIST BOX - SET NUMBER OF ENTRIES, SLIDER B (AES 175, 6)
       2.4.26 LIST BOX - SCROLL TO, SLIDER B (AES 175, 7)
   2.5 Font selector
       2.5.1 Calling procedure for font selector in a window
       2.5.2 Calling procedure for a modal font selector
       2.5.3 FONT SELECTOR - CREATE (AES 180)
       2.5.4 FONT SELECTOR - DELETE (AES 181)
       2.5.5 FONT SELECTOR - OPEN WINDOW (AES 182)
       2.5.6 FONT SELECTOR - CLOSE WINDOW (AES 183)
       2.5.7 FONT SELECTOR - GET NUMBER OF STYLES (AES 184, 0)
       2.5.8 FONT SELECTOR - GET STYLE ID (AES 184, 1)
       2.5.9 FONT SELECTOR - GET FONT NAME (AES 184, 2)
       2.5.10 FONT SELECTOR - GET FONT INFO (AES 184, 3)
       2.5.11 FONT SELECTOR - ADD USER FONTS (AES 185, 0)
       2.5.12 FONT SELECTOR - REMOVE USER FONTS (AES 185, 1)
       2.5.13 FONT SELECTOR - UPDATE WINDOW (AES 185, 2)
       2.5.14 FONT SELECTOR - HANDLE EVENT (AES 186)
       2.5.15 FONT SELECTOR - DO (AES 187)
   2.6 Print dialogs
       2.6.1 Calling procedure for print dialog in a window
       2.6.2 Calling procedure for a modal print dialog
       2.6.3 PRINT DIALOG - CREATE (AES 200)
       2.6.4 PRINT DIALOG - DELETE (AES 201)
       2.6.5 PRINT DIALOG - OPEN WINDOW (AES 202)
       2.6.6 PRINT DIALOG - CLOSE WINDOW (AES 203)
       2.6.7 PRINT DIALOG - GET SETTING STRUCTURE SIZE (AES 204, 0)
       2.6.8 PRINT DIALOG - ADD PRIVATE PRINTERS (AES 205, 0)
       2.6.9 PRINT DIALOG - REMOVE PRIVATE PRINTERS (AES 205, 1)
       2.6.10 PRINT DIALOG - UPDATE WINDOW (AES 205, 2)
       2.6.11 PRINT DIALOG - ADD PRIVATE DIALOGS (AES 205, 3)
       2.6.12 PRINT DIALOG - REMOVE PRIVATE DIALOGS (AES 205, 4)
       2.6.13 PRINT DIALOG - NEW DEFAULT SETTINGS (AES 205, 5)
       2.6.14 PRINT DIALOG - FREE SETTINGS (AES 205, 6)
       2.6.15 PRINT DIALOG - DEFAULT SETTINGS (AES 205, 7)
       2.6.16 PRINT DIALOG - VALIDATE SETTINGS (AES 205, 8)
       2.6.17 PRINT DIALOG - USE SETTINGS (AES 205, 9)
       2.6.18 PRINT DIALOG - HANDLE EVENT (AES 206)
       2.6.19 PRINT DIALOG - DO (AES 207)
   2.7 Conversion of extended object types

Appendix
========

 A Function and structure definitions

 B Binding

 C Sample source texts


 
1 Intentions, conditions, ovations
**********************************

The GEM user interface has altered a lot in the last ten years.
Current programs work with window dialogs that contain radio buttons, 
check boxes, popups, list boxes and many other enhancements.

As these extensions have not been integrated into TOS, programmers
are having to continuously "reinvent the wheel":
Usually the program is linked with a library that presumes that only 
the AES-functions of the first TOS version are present. All extensions 
are realised by the library's program code.

Unfortunately this has the disadvantage that the program size grows 
appreciably "simply" for reasons of appearance (which, under
multitasking, swallows just that portion of memory one doesn't have)
and the capabilities of newer OS versions are not or only partly used.

We have therefore chosen a different approach with the following 
prerequisites:


    Compact, resident extensions make frequently used routines 
     (window dialogs, list boxes, font selection, print dialogs)
     available.

    Highly flexible routines; this means no static limitation of the 
     number of dialogs or font selectors open simultaneously;  list boxes 
     that can manage more than just text objects, multiple selection,
     auto-scrolling, etc. ... .

    Facilities and extensions of the OS should be made use of
     (3D-effects, clipboard in editable fields, ...).

    Extended object types (group frames, radio buttons, etc.) are 
     assumed to be present so that the RSC-file stays compact.

    Object types missing in older OSs should be generated automatically
     by a short routine (-> ADAPTRSC.C).

    Design of the program interface should suit the  "personality"
     of the OS (so no "dino-tuning" with 3D-effects under TOS 1.0).


The result is WDIALOG: A system extension that makes MagiC-compatible
AES-extensions available.



1.1 Installation
================

Copy WDIALOG.PRG to the AUTO-folder and restart the system. From 
current experience an AUTO folder order is recommended in which WDIALOG 
is placed before NVDI.



1.2 Conditions
==============

The documentation for WDIALOG and the archive contents of WDIALOGE.LZH
are Public Domain, i.e. they may be copied and used freely. The archive 
may only be distributed complete!

Changes of the source codes to suit your own requirements are 
permitted. However you are NOT allowed to distribute these altered 
files. It is forbidden to distribute any of the files on a 
commercial basis or make a charge for distribution other than nominal 
copying and incidental costs.

The distribution of WDIALOG in connection with other software
products is permitted as long as no additional charges arise 
for the customer and the recommended sale price of this software 
does not exceed 50 DM (17).

Exception require written permission of the authors! 
Violations will be prosecuted!.

The copyright remains solely with the authors, Sven & Wilfried Behne

The following files belong to the WDIALOGE.LZH package:


    WDIALOG.TXT


    WDIALOG.PRG


    SAMPLE-folder with programs and source texts for WDLG_SMP.APP,
     XOBJ_SMP.APP, FNT_SMPL.APP, FNT_SMP2.APP, FNT_SMP3.APP, PDLGSMP1.APP,
     PDLGSMP2.APP, PDLGSMP3.APP and PDLGSMP4.APP.


    Snapshots of the example programs under TOS 1.04 and MagiC 4 (16-
     colour IMGs). (In HTML version only)


We are naturally always willing to listen to suggestions, wishes and 
bug reports.

Thomas Much and UDO6 are responsible for the HTML hypertext conversion.



1.3 Exclusion of liability
==========================

The liability for any kind of direct or indirect damage, consequential 
damage and third party damage through the use of the WDIALOG system 
extension are specifically excluded. No guarantee is offered about the 
completeness and correctness of the statements made in this documetation.



1.4 Disclaimer
==============

Most of the products mentioned here are protected by trade marks as a 
rule. The absence of specific references to this does not mean that 
these products are free of third-party rights.



2  WDIALOG Programmer's Guide
*****************************

Position at 04.05.98 (preliminary version).

This function description for WDIALOG is broken up into the following 
parts:



2.1 Data types and structures
=============================

The declarations and descriptions work with the following data types:

 +--------+----------+-------------+-----------------------------+	
 | BYTE 	|	8 bit |	Signed	|	   -128 to 127      	|
 +--------+----------+-------------+-----------------------------+ 
 | UBYTE 	|	8 bit |	Unsigned	|	     0 to 255			|
 +--------+----------+-------------+-----------------------------+ 
 | WORD  	|   16 bit |	Signed	|	  -32768 to 32767		|
 +--------+----------+-------------+-----------------------------+ 
 | UWORD 	|  16 bit  |	Unsigned	|	     0 to 65535		|
 +--------+----------+-------------+-----------------------------+ 
 | LONG	|  32 bit	 |	Signed	| -2147483648 to 2147483647	|
 +--------+----------+-------------+-----------------------------+ 
 | ULONG	|  32 bit	 |	Unsigned	|      0 to 4294967295		|
 +--------+----------+-------------+-----------------------------+


 
2.2 How do I recognise WDIALOG?
===============================

Sub-function 7 of appl_getinfo() returns in the lowest 5 bits of 
ap_gout1 whether the wdlg/lbox/fnts/fslx/pdlg_xx() functions are present.


Declaration:
WORD appl_getinfo( WORD ap_gtype, WORD *ap_gout1, WORD *ap_gout2,
                                  WORD *ap_gout3, WORD *ap_gout4 );

Call:
ap_greturn = appl_getinfo( 7, &ap_gout1, &ap_gout2,
                              &ap_gout3, &ap_gout4 );

Variable         Argument            Meaning
Inputs:

contrl[0]        130                 appl_getinfo
contrl[1]        1                   Entries in intin
contrl[3]        0                   Entries in addrin

intin[0]         ap_gtype            Number of the sub-function (7)

Outputs:

contrl[2]        5                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        ap_greturn          0: Error   1: All OK
intout[1]        ap_gout1            See description
intout[2]        ap_gout2
intout[3]        ap_gout3
intout[4]        ap_gout4

Bits in ap_gout1:
Bit 0:           wdlg_xx()-functions are present (1)
Bit 1:           lbox_xx()-functions are present (1)
Bit 2:           fnts_xx()-functions are present (1)
Bit 3:           fslx_xx()-functions are present (1) *
Bit 4:           pdlg_xx()-functions are present (1)

*: fslx_xx()-functions are only made available by MagiC.
   With TOS + WDIALOG the bit is not set. For a description of the
   file selector see fslx.txt (part of the MagiC docs).


Note: The function appl_getinfo() is not present in all AES versions. 
To check that it is present you should call appl_find("?AGI"). If 
appl_find() does not return an error then appl_getinfo() is present. 
This procedure also works with old TOS versions, as WDIALOG makes a 
rudimentary appl_getinfo()-function available and intercepts appl_find().

From V1.06 onwards  WDIALOG also supplies the form_popup()-function 
of MagiC in old TOS versions.

 

2.3 Window dialogs
==================

+------------------------+--------------------------------------------+
|	wdlg_create()		| Initialise window dialogs, allocate memory |
|	wdlg_open()		| Open window							|
|	wdlg_close()		| Close window                               |
|	wdlg_delete()		| Release memory                             |
+------------------------+--------------------------------------------+
|	wdlg_get_tree()	| Return pointer to object tree and          |
|					| surrounding rectangle                      |
|	wdlg_get_edit()	| Return edit object and cursor position     |
|	wdlg_get_udata()	| Return application-specific data           |
|	wdlg_get_handle()	| Return window handle                       |
+------------------------+--------------------------------------------+
|	wdlg_set_edit()	| Set edit object                            |
|	wdlg_set_tree()	| Set new object tree                        |
|	wdlg_set_size()	| Alter size of window and of object tree    |
|	wdlg_set_iconify()	| Iconify the window                         |
|	wdlg_set_uniconify()| Uniconify                                  |
+------------------------+--------------------------------------------+
|	wdlg_evnt()		| Manage events for the window dialog        |
|	wdlg_redraw()		|Trigger redraw of object tree               |
+------------------------+--------------------------------------------+



2.3.1 Calling procedure for window dialogs
------------------------------------------

Program start:
   .
   .
   .
Open dialog:               wdlg_create(), wdlg_open()
   .
   .
   .
Event loop:                wdlg_evnt() (calls callback function)
   .
   .
   .
Close dialog:              wdlg_close(), wdlg_delete()
   .
   .
   .
Program end:



2.3.2 WINDOW DIALOG - CREATE (AES 160)
--------------------------------------

This function allocates memory for a dialog structure and initialises it.


Declaration:
DIALOG  *wdlg_create( HNDL_OBJ handle_exit, OBJECT *tree,
                      void *user_data, WORD code, void *data, WORD flags );

Call:
dialog = wdlg_create( handle_exit, tree, user_data, code, data, WDLG_BKGD );

Variable         Argument            Meaning
Inputs:

contrl[0]        160                 wdlg_create
contrl[1]        2                   Entries in intin
contrl[3]        4                   Entries in addrin

intin[0]         code                Is passed to handle_exit() 
                                     in <clicks>
intin[1]         flags

addrin[0]        handle_exit         Pointer to the service function
addrin[1]        tree                Pointer to the object tree
addrin[2]        user_data           Pointer to user info
addrin[3]        data                Is passed to handle_exit() in <data>

Outputs:

contrl[2]        0                   Entries in intout
contrl[4]        1                   Entries in addrout

addrout[0]       dialog              Pointer to the dialog structure


Description of <handle_exit>:

<handle_exit> is the pointer to a service routine that is called, among 
others, by wdlg_evnt(). <handle_exit> is called if an exit or touchexit 
object was clicked on (in that case <obj> is a positive object number) 
or when an event has occurred that affects the dialog (in that case 
<obj> is negative und contains a corresponding function number such as 
HNDL_CLSD, for instance).

The parameters are passed via the stack and the routine may alter 
registers d0-d2/a0-a2.

Example of a service routine:


WORD cdecl handle_exit( DIALOG *dialog, EVNT *events, WORD obj,
                                       WORD clicks, void *data );
{
  if ( obj < 0 )             /* Event or object number? */
  {
                             /* All events except HNDL_CLSD are ignored
                                in this example */

     if ( obj == HNDL_CLSD ) /* Closer activated? */
        return( 0 );         /* Finish */


     if ( obj == HNDL_EDIT )
     {
        /* In window dialogs it may be useful to ignore key combinations
           with Control in input fields, so that keyboard shortcuts such
           as Ctrl-U, Ctrl-W or Ctrl-Q for instance may be evaluated in 
           the event loops of a program. In that case a 0 should be 
           returned after HNDL_EDIT so that the key is not evaluated 
           by objc_edit().
        */
     }
  }
  else                       /* An object has been selected */
  {
     switch ( obj )          /* Initiate action (if needed) */
     {

        case ...
          .
          .
          .
        case MY_EXIT_OBJECT: ..... return( 0 );   /* Finish */
     }
  }
  return( 1 );                     /* Continue */
}


The parameters have the following meanings:

dialog: Pointer to a dialog structure. One should not access the 
structure directly. The wdlg_xx functions should be used!

events: If <obj> is an object number (>= 0), then <events> points to 
the EVNT structure that was passed by wdlg_evnt().
Otherwise <events> is basically 0L and can  not be used for addressing.

obj: >= 0: Object number        < 0: Function number (see below)

clicks: Number of mouse clicks (if <obj> is an object number)

data: The contents depend on <obj>

Meaning of <data> depending on <obj>:

If <obj> is a (positive) object number, then the variable <user_data> 
is passed in <data> (see wdlg_create). <clicks> contains the number of 
mouse clicks on this object.


 +-------------+------------------------------------------------------+
 | HNDL_INIT:	| <data> is the variable passed by wdlg_create.       	|
 |  -1		| If handle_exit() returns 0, wdlg_create() does not  	|
 |			| create a dialog structure (error).                  	|
 |			| The variable <code> is passed in <clicks>.          	|
 +-------------+------------------------------------------------------+ 
 | HNDL_OPEN:	| <data> is the variable passed by wdlg_open.         	|
 | -5		| The variable <code> is passed in <clicks>.			|
 +-------------+------------------------------------------------------+ 
 | HNDL_CLSD:	| <data> is <user_data>. If handle_exit() returns 0,	|
 | -3		| the dialog will be closed -- wdlg_evnt() returns 0.  |
 |			| <events> points to the EVNT structure passed by      |
 |			| wdlg_evnt().                                         |
 +-------------+------------------------------------------------------+ 
 | HNDL_MOVE:	| <data> is <user_data>. If handle_exit() returns 0,   |
 | -9		| the dialog will be closed -- wdlg_evnt() returns 0.  |
 |			| <events> points to the EVNT structure passed by      |
 |			| wdlg_evnt().                                         |
 +-------------+------------------------------------------------------+ 
 | HNDL_TOPW:	| <data> is <user_data>. If handle_exit() returns 0,	|
 | -10		| the dialog will be closed -- wdlg_evnt() returns 0.	|
 |			| <events> points to the EVNT structure passed by 	|
 |			| wdlg_evnt().                                         |
 +-------------+------------------------------------------------------+ 
 | HNDL_UNTP:	| <data> is <user_data>. If handle_exit() returns 0,	|
 | -11		| the dialog will be closed -- wdlg_evnt() returns 0.	|
 |			| <events> points to the EVNT structure passed by      |
 |			| wdlg_evnt().									|
 +-------------+------------------------------------------------------+ 
 | HNDL_EDIT:	| <data> points to a word with the key code.			|
 | -6		| If handle_exit() returns 1, the key press will be    |
 |			| evaluated, if 0 ignored.                             |
 |			| <events> points to the EVNT structure passed by      |
 |			| wdlg_evnt().                                         |
 +-------------+------------------------------------------------------+ 
 | HNDL_EDDN:	| <data> points to a word with the key code.			|
 | -7		| <events> points to the EVNT structure passed by      |
 |			| wdlg_evnt().                                         |
 +-------------+------------------------------------------------------+ 
 | HNDL_EDCH:	| <data> points to a word with the object number of  	|
 | -8		| the new editable field.							|
 +-------------+------------------------------------------------------+ 
 | HNDL_MESG:	| <data> is <user_data>. If handle_exit() returns 0,	|
 | -2		| the dialog will be closed -- wdlg_evnt() returns 0.  |
 |			| <events> points to the EVNT structure passed by      |
 |			| wdlg_evnt().									|
 | 			| HNDL_MESG is only passed if a message code between   |
 |			| 20 and 39 was received that is not handled by other  |
 |			| opcodes.                                             |
 |			| Is required for iconification, for instance.         |
 |			|											|
 |			| Warning: This opcode is only present from MagiC 4.5  |
 |			| of 18.4.96        							|
 +-------------+------------------------------------------------------+ 

Of these function numbers one only has to react to HNDL_CLSD. All other 
events need only be paid attention to when needed.

If handle_exit is called with an unknown function number in <obj>, or 
one of the above function numbers is to be ignored, then 1 has to be 
returned.

Note: WDIALOG versions below 1.06 have an error in the edit object 
handling, which can lead to a crash with object trees with only one 
object (ROOT). If you absolutely want to display an empty window 
dialog, make sure that the tree is made up of at least two objects.



2.3.3 WINDOW DIALOG - OPEN (AES 161)
------------------------------------

OPEN opens a window with the title line <title> at the position <x>, <y>.
Before wdlg_open() returns to the caller, the service routine <handle_exit> 
(see above) is called with the function number HNDL_OPEN: 
handle_exit(dialog, HNDL_OPEN, code, data );


Declaration:
WORD wdlg_open( DIALOG *dialog, BYTE *title, WORD kind, WORD x,
                                WORD y, WORD code, void *data );

Call:
handle = wdlg_open( dialog, title, NAME + CLOSER + MOVER, x, y, code, data );

Variable         Argument    Meaning
Inputs:

contrl[0]        161         wdlg_open
contrl[1]        4           Entries in intin
contrl[3]        3           Entries in addrin

intin[0]         kind        Window components (NAME/MOVER/CLOSER)
intin[1]         x           x-coordinate of the dialog or -1 (centred)
intin[2]         y           y-coordinate of the dialog or -1 (centred)
intin[3]         code        Is passed to handle_exit() in <clicks>

addrin[0]        dialog      Pointer to the dialog structure
addrin[1]        title       Pointer to the window name or 0L
addrin[2]        data        Is passed to handle_exit() in <data>

Outputs:

contrl[2]        1           Entries in intout
contrl[4]        0           Entries in addrout

intout[0]        handle      Handle of the dialog window (0: Error)



2.3.4 WINDOW DIALOG - CLOSE (AES 162)
-------------------------------------

This function closes the window dialog <dialog>.


Declaration:
WORD wdlg_close( DIALOG *dialog );

Call:
wdlg_close( dialog );

Variable         Argument            Meaning
Inputs:

contrl[0]        162                 wdlg_close
contrl[1]        0                   Entries in intin
contrl[3]        1                   Entries in addrin

addrin[0]        dialog              Pointer to the dialog structure

Outputs:

contrl[2]        3                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        1
intout[1]        x                   Last x-coordinate of the dialog
intout[2]        y                   Last y-coordinate of the dialog


Note: Old WDIALOG versions do not return the window coordinates. In 
that case the binding enters -1, so that the dialog will be centred 
automatically at the next call.



2.3.5 WINDOW DIALOG - DELETE (AES 163)
--------------------------------------

This function releases the memory allocated for a window dialog.


Declaration:
WORD wdlg_delete( DIALOG *dialog );

Call:
wdlg_delete( dialog );

Variable         Argument            Meaning
Inputs:

contrl[0]        163                 wdlg_delete
contrl[1]        0                   Entries in intin
contrl[3]        1                   Entries in addrin

addrin[0]        dialog              Pointer to the dialog structure

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        1



2.3.6 WINDOW DIALOG - GET OBJECT TREE (AES 164, 0)
--------------------------------------------------

wdlg_get_tree() returns the size of the object tree and the size of the 
window (of the working area). If the dialog size has not been altered 
with wdlg_set_size(), then the working area corresponds to the GRECT of 
the root object.


Declaration:
WORD wdlg_get_tree( DIALOG *dialog, OBJECT **tree, GRECT *r );

Call:
wdlg_get_tree( dialog, &tree, &r );

Variable         Argument            Meaning
Inputs:

contrl[0]        164                 wdlg_get
contrl[1]        1                   Entries in intin
contrl[3]        3                   Entries in addrin

intin[0]         0                   wdlg_get_tree

addrin[0]        dialog              Pointer to the dialog structure
addrin[1]        tree                Pointer to object tree
addrin[2]        rect                Pointer to GRECT

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        1



2.3.7 WINDOW DIALOG - GET EDIT OBJECT (AES 164, 1)
--------------------------------------------------

This function returns the number of the current edit object. If the 
result is 0, then no edit object is active at the present time.


Declaration:
WORD wdlg_get_edit( DIALOG *dialog, WORD *cursor );

Call:
edit_obj = wdlg_get_edit( dialog, &cursor );

Variable         Argument            Meaning
Inputs:

contrl[0]        164                 wdlg_get
contrl[1]        1                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         1                   wdlg_get_edit

addrin[0]        dialog              Pointer to the dialog structure

Outputs:

contrl[2]        2                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        edit_obj            Number of the current edit object
                                     (or 0, if none is active)
intout[1]        cursor              Index of the character


Note: With old WDIALOG versions <cursor> is not returned. The binding 
ensures that -1 is entered in this case.



2.3.8 WINDOW DIALOG - GET USERDATA (AES 164, 2)
-----------------------------------------------

This function returns the variable <user_data> that was passed at the 
wdlg_create() call.


Declaration:
void *wdlg_get_udata( DIALOG *dialog );

Call:
user_data = wdlg_get_udata( dialog );

Variable         Argument            Meaning
Inputs:

contrl[0]        164                 wdlg_get
contrl[1]        1                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         2                   wdlg_get_udata

addrin[0]        dialog              Pointer to the dialog structure

Outputs:

contrl[2]        0                   Entries in intout
contrl[4]        1                   Entries in addrout

addrout[0]       user_data           The pointer user_data



2.3.9 WINDOW DIALOG - GET WINDOW HANDLE (AES 164, 3)
----------------------------------------------------

GET WINDOW HANDLE returns the handle of the dialog window.


Declaration:
WORD wdlg_get_handle( DIALOG *dialog );

Call:
handle = wdlg_get_handle( dialog );

Variable         Argument            Meaning
Inputs:

contrl[0]        164                 wdlg_get
contrl[1]        1                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         3                   wdlg_get_handle

addrin[0]        dialog              Pointer to the dialog structure

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        handle              Window handle



2.3.10 WINDOW DIALOG - SET EDIT OBJECT (AES 165, 0)
---------------------------------------------------

SET EDIT OBJECT activates an edit object, i.e. the cursor will be drawn 
in object <obj> and deleted from any previously active object.


Declaration:
WORD wdlg_set_edit( DIALOG *dialog, WORD obj );

Call:
edit_obj = wdlg_set_edit( dialog, new_edit_obj );

Variable         Argument         Meaning
Inputs:

contrl[0]        165              wdlg_set
contrl[1]        2                Entries in intin
contrl[3]        1                Entries in addrin

intin[0]         0                wdlg_set_edit
intin[1]         obj              Number of the new edit object
                                  (or 0, if none is to be active)

addrin[0]        dialog           Pointer to the dialog structure

Outputs:

contrl[2]        1                Entries in intout
contrl[4]        0                Entries in addrout

intout[0]        edit_obj         Number of the current edit object



2.3.11 WINDOW DIALOG - SET TREE (AES 165, 1)
--------------------------------------------

SET TREE represents a new object tree in a dialog. If the new root 
object has a different size, the window size will be adapted to suit.
The window contents will be updated in each case.


Declaration:
WORD wdlg_set_tree( DIALOG *dialog, OBJECT *new_tree );

Call:
wdlg_set_tree( dialog, new_tree );

Variable         Argument            Meaning
Inputs:

contrl[0]        165                 wdlg_set
contrl[1]        1                   Entries in intin
contrl[3]        2                   Entries in addrin

intin[0]         1                   wdlg_set_tree

addrin[0]        dialog              Pointer to the dialog structure
addrin[1]        new_tree            Pointer to the new object tree

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        1



2.3.12 WINDOW DIALOG - SET SIZE (AES 165, 2)
--------------------------------------------

With wdlg_set_size() one can alter the size of a window dialog. The 
GRECT <new_size> sets the new position and size of the window's working 
area. SET SIZE does not alter either the position or the size of the 
root object. If the root object is to be moved or enlarged then the 
object dimensions have to be altered before calling wdlg_set_size().


Declaration:
WORD wdlg_set_size( DIALOG *dialog, GRECT *new_size );

Call:
wdlg_set_size( dialog, new_size );

Variable         Argument            Meaning
Inputs:

contrl[0]        165                 wdlg_set
contrl[1]        1                   Entries in intin
contrl[2]        1                   Entries in intout
contrl[3]        2                   Entries in addrin
contrl[4]        0                   Entries in addrout

intin[0]         2                   wdlg_set_size

addrin[0]        dialog              Pointer to the dialog structure
addrin[1]        new_size            Pointer to GRECT

Outputs:

intout[0]        1


Note: The buttons must always lie completely within the window's 
working area, as form_button() pays no regard to the rectangle list.

The normal use for wdlg_set_size() are enlargeable dialogs, that have 
a Sizer object at the bottom right corner.



2.3.13 WINDOW DIALOG - ICONIFY (AES 165, 3)
-------------------------------------------

With wdlg_set_iconify() one can iconify a window dialog. The GRECT <g>
sets the new position and size of the window (external dimensions). 
Generally one will pass msg+4 here when one has received the message 
WM_ICONIFIY. But equally one can also pass a GRECT {-1,-1,-1,-1} which 
MagiC uses to ascertain the position.

ICONIFY alters the position and size of the root object. As one usually 
wants to display a different object tree for iconified windows, this 
can be passed in <tree> (otherwise set it to NULL).

Usually such an object tree consists only of the root object (G_BOX) 
and an icon (G_(C)ICON). If the icon (or another object) is to be 
centred in the window, the object number is passed in <obj>, otherwise 
-1. Furthermore one can specify a new window title. However the calling 
routine must ensure that the original title is restored at the 
wdlg_set_uniconify call.


Declaration:
WORD wdlg_set_iconify( DIALOG *dialog, GRECT *g, 
				  char *title, OBJECT *tree, WORD obj );

Call:
wdlg_set_iconify( dialog, g, title, tree, obj );

Variable         Argument            Meaning
Inputs:

contrl[0]        165                 wdlg_set
contrl[1]        2                   Entries in intin
contrl[2]        1                   Entries in intout
contrl[3]        4                   Entries in addrin

intin[0]         3                   wdlg_set_iconify
intin[1]         obj                 Object to be centred or -1

addrin[0]        dialog              Pointer to the dialog structure
addrin[1]        g                   Pointer to GRECT
addrin[2]        title               New window title or NULL
addrin[3]        tree                New window tree or NULL

Outputs:

intout[0]        1


Note: This function is only present from  WDIALOG 1.05 onwards. If it
is not present, intout[0] contains a 0.



2.3.14 WINDOW DIALOG - UNICONIFY (AES 165, 4)
---------------------------------------------

The counterpart to wdlg_set_iconify(). 
The GRECT <g> sets the new position and size of the window (external 
dimensions). Generally one will pass msg+4 here when one has received the 
message WM_UNICONIFIY. UNICONIFY alters the position and size of the root 
object. As one usually displayed a different object tree for iconified 
windows, the original tree can be passed in <tree> (otherwise set 
it to NULL). Furthermore one can specify the original window title if it 
was altered with wdlg_set_iconify.


Declaration:
WORD wdlg_set_uniconify( DIALOG *dialog, GRECT *g,
                       char *title, OBJECT *tree );

Call:
wdlg_set_uniconify( dialog, g, title, tree );

Variable         Argument            Meaning
Inputs:

contrl[0]        165                 wdlg_set
contrl[1]        1                   Entries in intin
contrl[2]        1                   Entries in intout
contrl[3]        4                   Entries in addrin

intin[0]         4                   wdlg_set_uniconify

addrin[0]        dialog              Pointer to the dialog structure
addrin[1]        g                   Pointer to GRECT
addrin[2]        title               New window title or NULL
addrin[3]        tree                New window tree or NULL

Outputs:

intout[0]        1


Note: This function is only present from  WDIALOG 1.05 onwards. If it 
is not present, intout[0] contains a 0.



2.3.15 WINDOW DIALOG - EVENT (AES 166)
--------------------------------------

This function must be called in an event-loop. The event-bits that 
refer to the window dialog are cleared in the bit vector <mwhich>.
Following wdlg_evnt() the EVNT-structure of the application can be used 
to evaluate the events intended for it. If wdlg_evnt() returns a 0, the 
window dialog has to be closed (call (wdlg_close()).


Declaration:
WORD wdlg_evnt( DIALOG *dialog, EVNT *events );

Call:
cont = wdlg_evnt( dialog, &events );

Variable         Argument            Meaning
Inputs:

contrl[0]        166                 wdlg_evnt
contrl[1]        0                   Entries in intin
contrl[3]        2                   Entries in addrin

addrin[0]        dialog              Pointer to the dialog structure
addrin[1]        events              Pointer to the EVNT-structure

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        cont                0: Close dialog
                                     1: All OK

Description of the EVNT-structure:

typedef struct
{
   WORD  mwhich;               /* Type of events */
   WORD  mx;                   /* X-coordinate of the mouse cursor */
   WORD  my;                   /* Y-coordinate of the mouse cursor */
   WORD  mbutton;              /* Pressed mouse button */
   WORD  kstate;               /* Status of the 'special' keys (kbshift) */
   WORD  key;                  /* Scancode of the pressed key */
   WORD  mclicks;              /* Number of mouse clicks */
   WORD  reserved[9];          /* Reserved */
   WORD  msg[16];              /* Message-buffer */
} EVNT;


Note: The Iconify-event is not supported by  wdlg_evnt(). Those wanting 
to install the Iconifier icon as a window object during wdlg_open() 
therefore have to evaluate this even and handle it themselves. The same 
applies if one want to install the Sizer icon as an object.



2.3.16 WINDOW DIALOG - REDRAW (AES 167)
---------------------------------------

REDRAW works in a similar way to objc_draw(), but unlike there the 
rectangle list of the dialog window is taken into account. If one wants 
to draw an object within the dialog then one should always use 
wdlg_redraw() and not objc_draw(). Before calling wdlg_redraw, just as 
before and after objc_draw(), a wind_update() call is necessary.


Declaration:
void wdlg_redraw( DIALOG *dialog, GRECT *rect, WORD obj, WORD depth );

Call:
wdlg_redraw( dialog, &rect, obj, MAX_DEPTH );

Variable         Argument            Meaning
Inputs:

contrl[0]        167                 wdlg_redraw
contrl[1]        2                   Entries in intin
contrl[3]        2                   Entries in addrin

intin[0]         obj                 Number of the start object
intin[1]         depth               Number of the plane/depth

addrin[0]        dialog              Pointer to the dialog structure
addrin[1]        rect                Pointer to the bounding GRECT

Outputs:

contrl[2]        0                   Entries in intout
contrl[4]        0                   Entries in addrout



2.4 List boxes
==============

+------------------------+---------------------------------------------+
| lbox_create()		| Create list box, allocate memory			 |
| lbox_update()		| Update AES objects                          |
| lbox_do()			| Manage button                               |
| lbox_delete()		| Release memory                              |
+------------------------+---------------------------------------------+
| lbox_cnt_items()		| Return the number of list items             |
| lbox_get_tree()		| Return pointer to object tree of the dialog |
| lbox_get_visible() or  |                                             |
| lbox_get_avis()		| Get number of visible list box items        |
|					| (Slider A)                                  |
| lbox_get_bvis()		|Get number of visible list box items         |
|					| (Slider B)                                  |
| lbox_get_udata()		|Get pointer to program-specific data         |
| lbox_get_first() or	|                                             |
| lbox_get_afirst()		| Return index of first visible item          |
|					| (Slider A)                                  |
| lbox_get_bfirst()		| Return index of first visible item          |
|					| (Slider B)                                  |
| lbox_get_slct_idx()	| Get index of first selected item            |
| lbox_get_items()		| Return pointer to first item of list        |
| lbox_get_item()		| Return pointer to nth item                  |
| lbox_get_slct_item()	| Return pointer to first selected item       |
| lbox_get_idx()		| Get index of an item                        |
| lbox_get_bentries		| Return number of visible items for Slider B |
+------------------------+---------------------------------------------+
| lbox_set_slider() or   |                                             |
| lbox_set_asldr()		| Set slider position (Slider A)              |
| lbox_set_bsldr()		| Set slider position (Slider B)              |
| lbox_set_items()		| Set new item list                           |
| lbox_free_items()		| Free items                                  |
| lbox_free_list()		| Free item list                              |
| lbox_set_bentries()	| Set number of items for Slider B            |
| lbox_scroll_to() or	|                                             |
| lbox_ascroll_to()		| Scroll contents of list box up to a given   |
|					| item (Slider A)                             |
| lbox_bscroll_to()		| Scroll contents of list box up to a given   |
|					| item (Slider B)                             |
+------------------------+---------------------------------------------+



2.4.1 Calling procedure for modal dialogs
-----------------------------------------

wind_update()           Lock screen
lbox_create()           Create list box
form_center()           Centre dialog
form_dial()             Buffer screen portion
   .
   .
Loop:       form_do() <----
               .           |
               .           |
            lbox_do() -----

   .
   .
End of loop (e.g. OK or Cancel activated)
   .
   .
Possibly lbox_get_slct_item()...
   .
   .
form_dial()             Send redraw message
wind_update()           Release screen
lbox_delete()           Release memory for list box



2.4.2 LIST BOX - CREATE (AES 170)
---------------------------------

This function allocates memory for a list box and initialises the 
objects by calling the routine <set> for each object passed in <objs>. 
However the list box will not be drawn!

Bit 0 of the variable <flags> determines whether the list box is a 
horizontal one (the first list item at left and last at right) or a 
vertical one (the first list item at top and last at bottom).
Independently of this main scrolling direction the list box can also 
have a second slider if the items themselves are to be scrolled. This 
can be sensible, for instance, with a vertical list box with text items 
that are wider than the box.


Declaration:
LIST_BOX *lbox_create( OBJECT *tree, SLCT_ITEM slct, SET_ITEM set,
                       LBOX_ITEM *items, WORD visible_a, WORD first_a,
                       WORD *ctrl_objs, WORD *objs, WORD flags,
                       WORD pause_a, void *user_data, DIALOG *dialog,
                       visible_b, first_b, entries_b, pause_b );

Call:
box = lbox_create( tree, slct_item, set_item, item_list, 10, 0,
                   ctrl_objs, objs, lbox_flags, 20, 0L, 0L, 10, 0, 40, 5 );

Variable         Argument   Meaning
Inputs:

contrl[0]        170        lbox_create
contrl[1]        4 or 8     Entries in intin
contrl[3]        8          Entries in addrin

intin[0]         visible_a  Number of visible entries (Slider A)
intin[1]         first_a    Index of the first visible entry (Slider A)
intin[2]         flags      Various flags
intin[3]         pause_a    Delay during scrolling in ms (Slider A)

intin[4]         visible_b  Number of visible items (Slider B)
intin[5]         first_b    First visible item (Slider B)
intin[6]         entries_b  Number of items (Slider B)
intin[7]         pause_b    Delay during scrolling in ms (Slider B)

addrin[0]        tree       Pointer to the object tree of the dialog
addrin[1]        slct       Pointer to selection routine
addrin[2]        set        Pointer to set routine
addrin[3]        items      Pointer to linked list with LBOX_ITEMs
addrin[4]        ctrl_objs  Pointer to a field with the object numbers
                            of the buttons and slider (5 entries)
addrin[5]        objs       Pointer to a field with the object numbers
                            of the list box items (<entries> entries)
addrin[6]        user_data  Pointer for application
addrin[7]        dialog     Pointer to the window dialog structure or 0L

Outputs:

contrl[2]        0            Entries in intout
contrl[4]        1            Entries in addrout

addrout[0]       box          Pointer to the list box structure or 0L


Both <slct> and <set> are functions whose parameters are passed on the 
stack. The functions may alter registers d0-d2/a0-a2.

<slct> is a pointer to a selection routine that is always called when 
an entry is selected or deselected:


typedef void (cdecl *SLCT_ITEM)( LIST_BOX *box, OBJECT *tree,
                                 struct _lbox_item *item,
                                 void *user_data,
                                 WORD obj_index, WORD last_state );




 <box>         points to the list box structure
 <tree>        points to the object tree of the dialog
 <item>        points to the LBOX_ITEM-structure of the selected entry
 <user_data>   is the pointer passed by lbox_create()
 <obj_index>   is the number of the selected object. For a double-click the 
			top bit is set, similar to form_do(). If is 0 it signifies 
			that no object is assigned to this entry; it is not visible. 
			Normally this only the case when one is scrolling and by 
			selecting a new object the (now no longer visible) selection 
			has to be cleared.
 <last_state>  is the previous status of the object.  can also have the 
			same value as selected>. In that case one can normally quit 
			the function immediately.



<slct> will also be called when the selection of an object is cleared! 
The variable <selected> from the LBOX_ITEM structure already contains 
the new status of the object when <slct> is called.

<set> points to the function that is to enter the contents of a 
LBOX_ITEM into an object of the list box dialog:


typedef WORD (cdecl *SET_ITEM)( LIST_BOX *box, OBJECT *tree,
                                struct _lbox_item *item,
                                WORD obj_index,
                                void *user_data, GRECT *rect,
                                WORD first );




   <box>        points to the list box structure
   <tree>       points to the object tree of the dialog
   <item>       points to the LBOX_ITEM structure of the entry to be set 
   <obj_index>  is the number of the object to be set
   <user_data>  is the pointer passed by lbox_create()
   <rect>       is the pointer to the GRECT for the object redraw or 0L
   <first>      contains the number of the first visible item for Slider B



For a list box that only contains text strings, <set> is typically a 
function that copies a string pointed to by the LBOX_ITEM structure 
into the object <index>.

<rect> is 0L when a redraw of the dialog box is executed or when 
lbox_update() has been called.

<rect> is not 0L when the user has selected or deselected an object, 
and points to the GRECT for the redraw. The return value of <set> is 
the number of the start object for objc_draw()/wdlg_redraw(). For 
entries in the list box that consist of several objects it is sometimes 
sensible to reduce the redraw rectangle when selecting/deselecting an 
object, or to alter the start object, to prevent unnecessary drawing 
operations and/or unnecessary flicker.

In most cases the list box routines call the function objc_draw()/
wdlg_redraw() after <set> to display the altered contents.

<first> contains the number of the first visible item for Slider B if 
the list box has two sliders. For a (vertical) list box with text 
strings and two sliders, when calling lbox_create(), for instance, one 
enters the number of visible characters in <visible_b>, the total 
string length in <entries_b> and the index of the first visible 
character in <first_b>. If the text is scrolled horizontally, <set> is 
called for all visible strings and the affected parts of the screen are 
redrawn or moved. If the list box has only one slider, <first> is 
always 0.

<items> points to the first item in a list from LBOX_ITEM. The structure 
used for the items must contain a pointer to its successor (next) as its 
first element and a word for the condition (selected) as the second:


   typedef struct _lbox_item
   {
      struct _lbox_item *next;
                         /* Pointer to the next entry in the list */
      WORD  selected;    /* Specifies whether the object is selected */
      WORD  data1;       /* Data for the program... */
      void  *data2;
      void  *data3;

   } LBOX_ITEM;


However the structure can well look like the following example with 
appropriate casting during the call:


   typedef struct
   {
      void  *next;
      WORD  selected;

      ... From here on to suit the application ...

   } LB_EXAMPLE;


<ctrl_objs> is a pointer to a field with 5 or 9 entries that contains the 
numbers of the control objects (buttons):

 ctrl_objs[0]:	Object number of the BOX or IBOX, that contains the actual 
			list box object
 ctrl_objs[1]:	Object number of the buttons for scrolling upwards or left
 ctrl_objs[2]:	Object number of the buttons for scrolling downwards or 
 			right
 ctrl_objs[3]:	Object number of the slider background box
 ctrl_objs[4]:	Object number of the slider box



If the list box has 2 sliders, ctrl_objs[5-8] contain the numbers of 
the objects for Slider B:

 ctrl_objs[5]:	Object number of the button for scrolling upwards or left
 ctrl_objs[6]:	Object number of the button for scrolling downwards or right
 ctrl_objs[7]:	Object number of the slider background box
 ctrl_objs[8]:	Object number of the slider box



The buttons, the slider and the slider background should have a 
TOUCHEXIT status. If the list box contains only buttons and no slider,
ctrl_objs[3/4 or 7/8] must contain -1.

<objs> is a field with <entries> entries that contains the numbers of the 
list box objects (the objects are normally children of ctrl_objs[0]).

   objs[0]:             Number of the first object
        .
        .
        .
   objs[entries - 1]:   Number of the last object


The objects should normally have TOUCHEXIT status.

The word <flags> influences the behaviour of the list box:

+-----+---------+-------------------------------------------------------+
| Bit |	State | Description								  	  |
+-----+---------+-------------------------------------------------------+
|  0	 |	0	 | The box scrolls horizontally                          |
|	 |  	1	 | The box scrolls vertically                            |
+-----+---------+-------------------------------------------------------+
|  1	 |	0	 | No automatic scrolling                                |
|	 |	1	 | Scrolling takes place automatically as soon as the    |
|	 |		 | mouse cursor is moved past the first or last item     |
|	 |		 | with the mouse button held down                       |
+-----+---------+-------------------------------------------------------+
|  2	 |	0	 | The selection routine will be called only after the   |
|	 |		 | automatic scrolling has finished, i.e. it will be     |
|	 |		 | called for the last selected entry.                   |
|	 |	1	 | With automatic scrolling the selection routine will   |
|	 |		 | be called for each selected entry during scrolling    |
+-----+---------+-------------------------------------------------------+
|  3	 |	0	 | When moving the slider a frame will be moved          |
|	 |		 | (graf_slidebox), the list box will only be updated    |
|	 |		 | after releasing the mouse button                      |
|	 |	1	 | The slider is a real-time slider                      |
+-----+---------+-------------------------------------------------------+
|  4	 |	0	 | Multiple selections within the list box are possible  |
|		1	 | Only one item can be selected                         |
+-----+---------+-------------------------------------------------------+
|  5	 |	0	 | Multiple selections possible without the Shift key    |
|	 |	1	 | Multiple selections only possible with the Shift key  |
+-----+---------+-------------------------------------------------------+
|  6	 | 	0	 | On selection the status is always SELECTED            |
|	 |	1	 | On selection the status is always changed             |
+-----+---------+-------------------------------------------------------+
|  7	 |	0	 | The list box has only one slider                      |
|	 |	1	 | The list box has two sliders                          |
+-----+---------+-------------------------------------------------------+


#define  LBOX_VERT   1      /* List box with vertical slider */
#define  LBOX_AUTO   2      /* Auto scrolling */
#define  LBOX_AUTOSLCT  4   /* Automatic display during auto scrolling */
#define  LBOX_REAL   8      /* Real-time slider */
#define  LBOX_SNGL   16     /* Only one selectable entry */
#define  LBOX_SHFT   32     /* Multiple selections with Shift */
#define  LBOX_TOGGLE 64     /* On selection change status of an entry */
#define  LBOX_2SLDRS 128    /* Support 2 sliders */


The flag LBOX_SNGL can also be combined with LBOX_SHFT or LBOX_TOGGLE 
to permit deselection in a list box with only one selectable entry.
LBOX_SNGL + LBOX_SHFT means that the selected entry can be deselected 
by a click with a pressed Shift key. LBOX_SNGL + LBOX_TOGGLE causes a 
click to deselect a selected entry.

The pointer <items> can also be 0L if the list box is still empty and does 
not contain any entries.



2.4.3 LIST BOX - UPDATE (AES 171)
---------------------------------

UPDATE updates the contents of the list box objects, i.e. the function 
<set> (see above) is called for each of the objects. If <rect> is not 0L
it will be regarded as a pointer to a GRECT that will be used for the 
redraw of the list box. Otherwise the objects will only be updated but 
not drawn.


Declaration:
void lbox_update( LIST_BOX *box, GRECT *rect );

Call:
lbox_update( box, &redraw_rect );

Variable         Argument        Meaning
Inputs:

contrl[0]        171             lbox_update
contrl[1]        0               Entries in intin
contrl[3]        2               Entries in addrin

addrin[0]        box             Pointer to the list box structure
addrin[1]        rect            Pointer to the redraw GRECT or 0L

Outputs:

contrl[2]        0               Entries in intout
contrl[4]        0               Entries in addrout



2.4.4 LIST BOX - DO (AES 172)
-----------------------------

DO reacts to the activation of a button. This function should be called 
after form_do() (or by the service function of the window dialog). If one 
of the entries of the list box was selected with a double-click, lbox_do() 
returns -1. The dialog should then be closed as if the OK button had 
been activated.

lbox_do() recognises double-clicks by the set topmost bit of the object 
number <obj> (object number | 0x8000). For the returned object number 
<slct_obj> the top bit is always cleared.


Declaration:
WORD lbox_do( LIST_BOX *box, WORD obj );

Call:
slct_obj = lbox_do( box, obj );

Variable         Argument          Meaning
Inputs:

contrl[0]        172               lbox_do
contrl[1]        1                 Entries in intin
contrl[3]        1                 Entries in addrin

intin[0]         obj               Number of the selected object

addrin[0]        box               Pointer to the list box structure

Outputs:

contrl[2]        1                 Entries in intout
contrl[4]        0                 Entries in addrout

intout[0]        slct_obj          Number of the selected object
                                   or -1, if there was a double-click 
                                   on an entry

 

2.4.5 LIST BOX - DELETE (AES 173)
---------------------------------

DELETE releases the memory allocated for the list box.


Declaration:
WORD lbox_delete( LIST_BOX *box );

Call:
lbox_delete( box );

Variable         Argument            Meaning
Inputs:

contrl[0]        173                 lbox_delete
contrl[1]        0                   Entries in intin
contrl[3]        1                   Entries in addrin

addrin[0]        box                 Pointer to the list box structure

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        1

 

2.4.6 LIST BOX - COUNT ITEMS (AES 174, 0)
-----------------------------------------

COUNT ITEMS counts the items of the chained list.


Declaration:
WORD lbox_cnt_items( LIST_BOX *box );

Call:
no = lbox_cnt_items( box );

Variable         Argument            Meaning
Inputs:

contrl[0]        174                 lbox_get
contrl[1]        1                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         0                   lbox_cnt_items

addrin[0]        box                 Pointer to the list box structure

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        no                  Number of the items in the list



2.4.7 LIST BOX - GET TREE (AES 174, 1)
--------------------------------------

GET TREE returns the pointer to the object tree of the dialog box.


Declaration:
OBJECT  *lbox_get_tree( LIST_BOX *box );

Call:
tree = lbox_get_tree( box );

Variable         Argument            Meaning
Inputs:

contrl[0]        174                 lbox_get
contrl[1]        1                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         1                   lbox_get_tree

addrin[0]        box                 Pointer to the list box structure

Outputs:

contrl[2]        0                   Entries in intout
contrl[4]        1                   Entries in addrout

addrout[0]       tree                Pointer to the object tree of the
                                     dialog



2.4.8 LIST BOX - GET NUMBER OF VISIBLE ITEMS, SLIDER A (AES 174, 2)
-------------------------------------------------------------------

GET VISIBLE returns the number of visible items.


Declaration:
WORD lbox_get_visible( LIST_BOX *box );

Call:
entries = lbox_get_visible( box );
               or
entries = lbox_get_avisb( box );

Variable         Argument            Meaning
Inputs:

contrl[0]        174                 lbox_get
contrl[1]        1                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         2                   lbox_get_size

addrin[0]        box                 Pointer to the list box structure

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        entries             Number of visible items



2.4.9 LIST BOX - GET USER DATA (AES 174, 3)
-------------------------------------------

...returns the pointer <user_data>.


Declaration:
void *lbox_get_udata( LIST_BOX *box );

Call:
user_data = lbox_get_udata( box );

Variable         Argument            Meaning
Inputs:

contrl[0]        174                 lbox_get
contrl[1]        1                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         3                   lbox_get_udata

addrin[0]        box                 Pointer to the list box structure

Outputs:

contrl[2]        0                   Entries in intout
contrl[4]        1                   Entries in addrout

addrout[0]       user_data



2.4.10 LIST BOX - GET FIRST VISIBLE ITEM, SLIDER A (AES 174, 4)
---------------------------------------------------------------

GET FIRST returns the index of the first visible item.


Declaration:
WORD lbox_get_first( LIST_BOX *box );

Call:
first = lbox_get_first( box );
               or
first = lbox_get_afirst( box );

Variable         Argument            Meaning
Inputs:

contrl[0]        174                 lbox_get
contrl[1]        1                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         4                   lbox_get_first

addrin[0]        box                 Pointer to the list box structure

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        first               Index of the first visible item



2.4.11 LIST BOX - GET INDEX of SELECTED ITEM (AES 174, 5)
---------------------------------------------------------

Establish the index of the first selected item. If no item in the 
list is selected then -1 will be returned.


Declaration:
WORD lbox_get_slct_idx( LIST_BOX *box );

Call:
index = lbox_get_slct_idx( box );

Variable         Argument            Meaning
Inputs:

contrl[0]        174                 lbox_get
contrl[1]        1                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         5                   lbox_get_slct_idx

addrin[0]        box                 Pointer to the list box structure

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        index               Index of the selected item



2.4.12 LIST BOX - GET ITEMS (AES 174, 6)
----------------------------------------

GET ITEMS returns a pointer to the list of the LBOX_ITEMs


Declaration:
LBOX_ITEM  *lbox_get_items( LIST_BOX *box );

Call:
items = lbox_get_items( box );

Variable         Argument            Meaning
Inputs:

contrl[0]        174                 lbox_get
contrl[1]        1                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         6                   lbox_get_items

addrin[0]        box                 Pointer to the list box structure

Outputs:

contrl[2]        0                   Entries in intout
contrl[4]        1                   Entries in addrout

addrout[0]       items               Pointer to the chained list



2.4.13 LIST BOX - GET ITEM (AES 174, 7)
---------------------------------------

GET ITEM returns a pointer to item <n> of the list.


Declaration:
LBOX_ITEM  *lbox_get_item( LIST_BOX *box, WORD n );

Call:
item = lbox_get_item( box, n );

Variable         Argument            Meaning
Inputs:

contrl[0]        174                 lbox_get
contrl[1]        2                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         7                   lbox_get_item
intin[1]         n                   Index des items

addrin[0]        box                 Pointer to the list box structure

Outputs:

contrl[2]        0                   Entries in intout
contrl[4]        1                   Entries in addrout

addrout[0]       item                Pointer to item n or 0L



2.4.14 LIST BOX - GET SELECTED ITEM (AES 174, 8)
------------------------------------------------

GET SELECTED ITEM returns a pointer to the first selected item of the 
list.


Declaration:
LBOX_ITEM *lbox_get_slct_item( LIST_BOX *box );

Call:
item = lbox_get_slct_item( box );

Variable         Argument            Meaning
Inputs:

contrl[0]        174                 lbox_get
contrl[1]        1                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         8                   lbox_get_slct_item

addrin[0]        box                 Pointer to the list box structure

Outputs:

contrl[2]        0                   Entries in intout
contrl[4]        1                   Entries in addrout

addrout[0]       item                Pointer to item n or 0L



2.4.15 LIST BOX - GET ITEM INDEX (AES 174, 9)
---------------------------------------------

This function returns the index <n> of the item <item>.
If <item> is not an element of the list, the return value is -1.


Declaration:
WORD lbox_get_idx( LBOX_ITEM *items, LBOX_ITEM *search );

Call:
n = lbox_get_idx( items, search );

Variable         Argument      Meaning
Inputs:

contrl[0]        174           lbox_get
contrl[1]        1             Entries in intin
contrl[3]        2             Entries in addrin

intin[0]         9             lbox_get_idx

addrin[0]        items         Pointer to the first item of the list
addrin[1]        search        Pointer to the item to be found

Outputs:

contrl[2]        1             Entries in intout
contrl[4]        0             Entries in addrout

intout[0]        n             Index of the item



2.4.16 LIST BOX - GET NUMBER OF VISIBLE ITEMS, SLIDER B (AES 174, 10)
---------------------------------------------------------------------

GET VIS returns the number of visible entries.


Declaration:
WORD lbox_get_bvis( LIST_BOX *box );

Call:
entries = lbox_get_bvis( box );

Variable         Argument            Meaning
Inputs:

contrl[0]        174                 lbox_get
contrl[1]        1                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         10                  lbox_get_bvis

addrin[0]        box                 Pointer to the list box structure

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        entries             Number of visible entries



2.4.17 LIST BOX - GET NUMBER OF ITEMS, SLIDER B (AES 174, 11)
-------------------------------------------------------------

... returns the number of items for Slider B.


Declaration:
WORD lbox_get_bentries( LIST_BOX *box );

Call:
entries = lbox_get_bentries( box );

Variable         Argument            Meaning
Inputs:

contrl[0]        174                 lbox_get
contrl[1]        1                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         11                  lbox_get_bentrs

addrin[0]        box                 Pointer to the list box structure

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        entries             Number of items



2.4.18 LIST BOX - GET FIRST VISIBLE ITEM, SLIDER B (AES 174, 12)
----------------------------------------------------------------

GET FIRST returns the index of the first visible item (Slider B!).


Declaration:
WORD lbox_get_bfirst( LIST_BOX *box );

Call:
first = lbox_get_bfirst( box );

Variable         Argument            Meaning
Inputs:

contrl[0]        174                 lbox_get
contrl[1]        1                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         12                  lbox_get_bfirst

addrin[0]        box                 Pointer to the list box structure

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        first               Index of the first visible item



2.4.19 LIST BOX - SET SLIDER A (AES 175, 0)
-------------------------------------------

This function positions Slider A and draws it within the redraw 
rectangle <rect>. The contents of the list box will not be updated, 
so one may have to call lbox_update(). 
If <rect> is 0L, then only the position of the slider objects will 
be altered, but the objects will not be drawn.


Declaration:
void lbox_set_slider( LIST_BOX *box, WORD first, GRECT *rect );

Call:
lbox_set_slider( box, first, &rect );
       or
lbox_set_asldr( box, first, &rect );

Variable         Argument       Meaning
Inputs:

contrl[0]        175            lbox_set
contrl[1]        2              Entries in intin
contrl[3]        2              Entries in addrin

intin[0]         0              lbox_set_slider
intin[1]         first          Index of the first visible entry

addrin[0]        box            Pointer to the list box structure
addrin[1]        rect           Pointer to redraw rectangle or 0L

Outputs:

contrl[2]        0              Entries in intout
contrl[4]        0              Entries in addrout



2.4.20 LIST BOX - SET NEW ITEM LIST (AES 175, 1)
------------------------------------------------

This function sets a new list with list box entries. The old list must 
first be freed with lbox_free_items().


Declaration:
void lbox_set_items( LIST_BOX *box, LBOX_ITEM *items );

Call:
lbox_set_items( box, items );

Variable         Argument            Meaning
Inputs:

contrl[0]        175                 lbox_set
contrl[1]        1                   Entries in intin
contrl[3]        2                   Entries in addrin

intin[0]         1                   lbox_set_items

addrin[0]        box                 Pointer to the list box structure
addrin[1]        items

Outputs:

contrl[2]        0                   Entries in intout
contrl[4]        0                   Entries in addrout


The pointer <items> can also be 0L if the list box is empty 
and contains no entries.



2.4.21 LIST BOX - FREE ITEMS (AES 175, 2)
-----------------------------------------

This function frees the memory for the chained list from LBOX_ITEMs. 
A prerequisite for this is that memory was allocated with Malloc() for 
each item of the list.

If custom memory management was used for LBOX_ITEMs (e.g. the C 
standard functions), then a custom function must also be called to free 
the memory.


Declaration:
void lbox_free_items( LIST_BOX *box );

Call:
lbox_free_items( box );

Variable         Argument            Meaning
Inputs:

contrl[0]        175                 lbox_set
contrl[1]        1                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         2                   lbox_free_items

addrin[0]        box                 Pointer to the list box structure

Outputs:

contrl[2]        0                   Entries in intout
contrl[4]        0                   Entries in addrout



2.4.22 LIST BOX - FREE ITEM LIST (AES 175, 3)
---------------------------------------------

This functions works exactly the same as lbox_free_items(). 
In contrast to that however lbox_free_list() is called with the pointer 
on the first LBOX_ITEM of the list.


Declaration:
void lbox_free_list( LBOX_ITEM *items );

Call:
lbox_free_list( items );

Variable         Argument            Meaning
Inputs:

contrl[0]        175                 lbox_set
contrl[1]        1                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         3                   lbox_free_list

addrin[0]        items               Pointer to linked list with LBOX_ITEMs

Outputs:

contrl[2]        0                   Entries in intout
contrl[4]        0                   Entries in addrout



2.4.23 LIST BOX - SCROLL TO, SLIDER A (AES 175, 4)
--------------------------------------------------

This function positions Slider A and updates the contents of the 
list box. <box_rect> is the redraw rectangle for the list box 
and <slider_rect> ist the redraw rectangle for the slider.

SCROLL TO works in principle like a call of lbox_set_slider() 
followed by a lbox_update(); scrolling 
takes place if possible, however, to reduce the amount of drawing required.
One may therefore not use lbox_scroll_to() if the item list of the list 
box has changed.


Declaration:
void lbox_scroll_to( LIST_BOX *box, WORD first, GRECT *box_rect,
                                              GRECT *slider_rect );

Call:
lbox_scroll_to( box, first, &box_rect, &slider_rect );
      or
lbox_ascroll_to( box, first, &box_rect, &slider_rect );

Variable         Argument         Meaning
Inputs:

contrl[0]        175              lbox_set
contrl[1]        2                Entries in intin
contrl[3]        3                Entries in addrin

intin[0]         4                lbox_scroll_to
intin[1]         first            Index of the first visible entry

addrin[0]        box              Pointer to the list box structure
addrin[1]        box_rect         Pointer to redraw rectangle or 0L
addrin[2]        slider_rect      Pointer to redraw rectangle or 0L

Outputs:

contrl[2]        0                Entries in intout
contrl[4]        0                Entries in addrout



2.4.24 LIST BOX - SET SLIDER B (AES 175, 5)
-------------------------------------------

This function positions Slider B and draws it within the redraw 
rectangle <rect>. The contents of the list box will not be updated, 
so one may have to call lbox_update().
If <rect> is 0L, then only the position of the slider objects will 
be altered, but the objects will not be drawn.


Declaration:
void lbox_set_bsldr( LIST_BOX *box, WORD first, GRECT *rect );

Call:
lbox_set_bsldr( box, first, &rect );

Variable         Argument       Meaning
Inputs:

contrl[0]        175            lbox_set
contrl[1]        2              Entries in intin
contrl[3]        2              Entries in addrin

intin[0]         5              lbox_set_bsldr
intin[1]         first          Index of the first visible entry

addrin[0]        box            Pointer to the list box structure
addrin[1]        rect           Pointer to redraw rectangle or 0L

Outputs:

contrl[2]        0              Entries in intout
contrl[4]        0              Entries in addrout



2.4.25 LIST BOX - SET NUMBER OF ENTRIES, SLIDER B (AES 175, 6)
--------------------------------------------------------------

This Function sets the number of items (the subdivisions) for Slider B.


Declaration:
void lbox_set_bentries( LIST_BOX *box, WORD entries );

Call:
lbox_set_bentries( box, entries );

Variable         Argument            Meaning
Inputs:

contrl[0]        175                 lbox_set
contrl[1]        2                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         7                   lbox_set_bentries
intin[1]         entries             Number of items

addrin[0]        box                 Pointer to the list box structure

Outputs:

contrl[2]        0                   Entries in intout
contrl[4]        0                   Entries in addrout



2.4.26 LIST BOX - SCROLL TO, SLIDER B (AES 175, 7)
--------------------------------------------------

This function positions Slider B and updates the contents of the list 
box. <box_rect> is the redraw rectangle for the list box and 
<slider_rect> is the redraw rectangle for the slider.

SCROLL TO works in principle like a call of lbox_set_bslider() followed 
by a lbox_update(); scrolling takes place if possible, however, to 
reduce the amount of drawing required.
One may therefore not use lbox_scroll_to() if the item list of the list 
box has changed.


Declaration:
void lbox_bscroll_to( LIST_BOX *box, WORD first, GRECT *box_rect,
                                              GRECT *slider_rect );

Call:
lbox_bscroll_to( box, first, &box_rect, &slider_rect );

Variable         Argument       Meaning
Inputs:

contrl[0]        175            lbox_set
contrl[1]        2              Entries in intin
contrl[3]        3              Entries in addrin

intin[0]         7              lbox_bscroll_to
intin[1]         first          Index of the first visible entry

addrin[0]        box            Pointer to the list box structure
addrin[1]        box_rect       Pointer to redraw rectangle or 0L
addrin[2]        slider_rect    Pointer to redraw rectangle or 0L

Outputs:

contrl[2]        0              Entries in intout
contrl[4]        0              Entries in addrout



2.5 Font selector
=================

+----------------------+------------------------------------------------+
| fnts_create()	   |	Initiate font selector, allocate memory        |
| fnts_open()		   |	Open selection dialog in window                |
| fnts_close()	   	   |	Close window                                   |
| fnts_delete()	   |	Free memory                                    |
+----------------------+------------------------------------------------+
| fnts_get_no_styles() |	Get number of styles of a font family          |
| fnts_get_style()	   |	Return ID of nth style of a family             |
| fnts_get_name()	   |	Return name of a font                          |
+----------------------+------------------------------------------------+
| fnts_add()		   |	Add user fonts to selection (e.g. Signum fonts)|
| fnts_remove()	   |	Remove user fonts from list                    |
+----------------------+------------------------------------------------+
| fnts_evnt()		   |	Manage events for dialog in a window           |
+----------------------+------------------------------------------------+
| fnts_do()		   |	Display modal dialog                           |
+----------------------+------------------------------------------------+



2.5.1 Calling procedure for font selector in a window
-----------------------------------------------------


Program start:             fnts_create()
   .
   .
   .
Calling the font selector: fnts_open()
   .
   .
   .
Event loop:                fnts_evnt()
   .                             .
   .                             .
   ......Possibly fnts_get_no_styles()/fnts_get_style()/...
                 (depending on the status of the checkboxes)
   .                               .
   .                             .
Closing the font selector: fnts_close()
   .
   .
   .
Program end:               fnts_delete()



2.5.2 Calling procedure for modal font selector
-----------------------------------------------


Program start:             fnts_create()
   .
   .
   .
Calling the font selector: fnts_do()
   .
   .
   ......Possibly fnts_get_no_styles()/fnts_get_style()/...
               (depending on status of the checkboxes)
   .
   .
Program end:               fnts_delete()



2.5.3 FONT SELECTOR - CREATE (AES 180)
--------------------------------------

This function initialises the font selector. If <no_fonts> is 0, 
vst_load_fonts() is called with <vdi_handle>. Otherwise an assumption is 
made that <no_fonts> is the number of all fonts available via <vdi_handle>, 
i.e. the number of all system fonts (work_out[10] for v_opnvwk()/
vq_extnd()) plus the number of fonts loaded in later (return value of 
vst_load_fonts()).


Declaration:
FNT_DIALOG *fnts_create( WORD vdi_handle, WORD no_fonts,
                         WORD font_flags, WORD dialog_flags,
                         BYTE *sample, BYTE *opt_button );

Call:
fnt_dialog = fnts_create( vdi_handle, 0, 0xf, "The quick brown..." );

Variable         Argument       Meaning
Inputs:

contrl[0]        180            fnts_create
contrl[1]        4              Entries in intin
contrl[3]        2              Entries in addrin

intin[0]         vdi_handle     Handle of the workstation to be used
intin[1]         no_fonts       Number of available fonts or 0,
                                if vst_load_fonts() is to be called
intin[2]         font_flags     Type of fonts to be displayed
intin[3]         dialog_flags   Appearance of the dialog

addrin[0]        sample         Pointer to string for the sample text
addrin[1]        opt_button     Pointer to string for optional button 
                                or 0L

Outputs:

contrl[2]        0               Entries in intout
contrl[4]        1               Entries in addrout

addrout[0]       fnt_dialog      Pointer to management structure

Description of <font_flags>:

#define  FNTS_BTMP   1           /* Display bitmap fonts */
#define  FNTS_OUTL   2           /* Display vector fonts */
#define  FNTS_MONO   4           /* Display mono-spaced fonts */
#define  FNTS_PROP   8           /* Display proportional fonts */

Description of <dialog_flags>:

#define  FNTS_3D     1           /* Display selector in 3D-look */


Note: Depending on system configuration, this function may well take 
1 second (possibly even more), so it should be called at program start and 
not just immediately before displaying the font selector.

Please note: The font selector alters the attributes of the workstation 
described by <vdi_handle>. If one wants to use the workstation passed with 
fnts_create() also for other purposes, the attributes have to be set first 
each time, as they may have been altered meantime by the font selector.



2.5.4 FONT SELECTOR - DELETE (AES 181)
--------------------------------------

This function releases the memory allocated for the font selector.
If <vdi_handle> is not 0, then vst_unload_fonts() will be called.


Declaration:
WORD fnts_delete( FNT_DIALOG *fnt_dialog, WORD vdi_handle );

Call:
fnts_delete( fnt_dialog, vdi_handle );

Variable         Argument            Meaning
Inputs:

contrl[0]        181                 fnts_delete
contrl[1]        1                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         vdi_handle          Handle of the Workstation or 0,
                                     if vst_unload_fonts() is not
                                     to be called

addrin[0]        fnt_dialog          Pointer to management structure

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        1



2.5.5 FONT SELECTOR - OPEN WINDOW (AES 182)
-------------------------------------------

OPEN WINDOW opens a window dialog with the font selector. The handle of 
the window will be returned if no error has arisen. In case of error the 
return value is 0.


Declaration:
WORD fnts_open( FNT_DIALOG *fnt_dialog, WORD button_flags,
                 WORD x, WORD y, LONG id, LONG pt, LONG ratio );

Call:
whdl = fnts_open( fnt_dialog, 0x3f0f, -1, -1, id, pt, ratio );

Variable         Argument         Meaning
Inputs:

contrl[0]        182              fnts_open
contrl[1]        9                Entries in intin
contrl[3]        1                Entries in addrin

intin[0]         button_flags     Flags for supported buttons
intin[1]         x                x-coordinate of the window or -1
                                  (centred)
intin[2]         y                y-coordinate of the window or -1
                                  (centred)
intin[3/4]       id               Font ID
intin[5/6]       pt               Height in 1/65536 point
intin[7/8]       ratio            Width/height ratio in 1/65536

addrin[0]        fnt_dialog       Pointer to management structure

Outputs:

contrl[2]        1                Entries in intout
contrl[4]        0                Entries in addrout

intout[0]        whdl             Handle of the window or 0 (error)

Description of <button_flags>:

#define  FNTS_SNAME     0x01  /* Select checkbox for names */
#define  FNTS_SSTYLE    0x02  /* Select checkbox for style */
#define  FNTS_SSIZE     0x04  /* Select checkbox for height  */
#define  FNTS_SRATIO    0x08  /* Select checkbox for width/height ratio */

#define  FNTS_CHNAME    0x0100  /* Display checkbox for names */
#define  FNTS_CHSTYLE   0x0200  /* Display checkbox for style */
#define  FNTS_CHSIZE    0x0400  /* Display checkbox for height */
#define  FNTS_CHRATIO   0x0800  /* Display checkbox for width/height 
							ratio */
#define  FNTS_RATIO     0x1000  /* Width/height ratio adjustable */
#define  FNTS_BSET      0x2000  /* Button "Set" selectable */
#define  FNTS_BMARK     0x4000  /* Button "Mark" selectable */



2.5.6 FONT SELECTOR - CLOSE WINDOW (AES 183)
--------------------------------------------

CLOSE WINDOW closes the window of the font selector.


Declaration:
WORD fnts_close( FNT_DIALOG *fnt_dialog, WORD *x, WORD *y );

Call:
fnts_close( *fnt_dialog, &x, &y );

Variable         Argument            Meaning
Inputs:

contrl[0]        183                 fnts_close
contrl[1]        0                   Entries in intin
contrl[3]        1                   Entries in addrin

addrin[0]        fnt_dialog          Pointer to management structure

Outputs:

contrl[2]        3                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        1
intout[1]        x                   Last x-coordinate of the dialog
intout[2]        y                   Last y-coordinate of the dialog


Note: Old WDIALOG versions do not return the window coordinates. In 
that case the binding enters -1, so that the 
dialog will be centred automatically at the next call.



2.5.7 FONT SELECTOR - GET NUMBER OF STYLES (AES 184, 0)
-------------------------------------------------------

This function returns the number of fonts that belong to the same 
family as the font <id>, i.e. the number of styles in the family.
<id> is the ID of a font of this family, that may have been returned 
by fnts_evnt() for instance.


Declaration:
WORD fnts_get_no_styles( FNT_DIALOG *fnt_dialog, LONG id );

Call:
no_fonts = WORD  fnts_get_no_styles( fnt_dialog, id );

Variable         Argument            Meaning
Inputs:

contrl[0]        184                 fnts_get
contrl[1]        3                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         0                   fnts_get_no_styles



intin[1/2]       id                  ID of a font of the family

addrin[0]        fnt_dialog          Pointer to management structure

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        no_fonts            Number of styles belonging to the 
                                     family



2.5.8 FONT SELECTOR - GET STYLE ID (AES 184, 1)
-----------------------------------------------

GET STYLE ID returns the ID of the <index>-th font of the family 
to which the font <id> also belongs. <index> must be a number 
between 1 and the result of fnts_get_no_styles().


Declaration:
LONG fnts_get_style( FNT_DIALOG *fnt_dialog, LONG id, WORD index );

Call:
style_id = fnts_get_style( fnt_dialog, id, index );

Variable         Argument            Meaning
Inputs:

contrl[0]        184                 fnts_get
contrl[1]        4                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         1                   fnts_get_style
intin[1/2]       id                  ID of a font of the family
intin[3]         index               Index within the family

addrin[0]        fnt_dialog          Pointer to management structure

Outputs:

contrl[2]        2                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0/1]      style_id            ID of the <index>-th font of 
                                     the family


2.5.9 FONT SELECTOR - GET FONT NAME (AES 184, 2)
------------------------------------------------

GET FONT NAME returns the full name, the family name and the style 
for the font <id>.


Declaration:
WORD fnts_get_name( FNT_DIALOG *fnt_dialog, LONG id,
                    BYTE *full_name, BYTE *family_name,
                    BYTE *style_name );

Call:
ret = fnts_get_name( FNT_DIALOG *fnt_dialog, id, &full_name,
                                  &family_name, &style_name );

Variable         Argument       Meaning
Inputs:

contrl[0]        184            fnts_get
contrl[1]        3              Entries in intin
contrl[3]        4              Entries in addrin

intin[0]         2              fnts_get_name
intin[1/2]       id             Font ID

addrin[0]        fnt_dialog     Pointer to management structure
addrin[1]        full_name      Pointer to the full name or 0L
addrin[2]        family_name    Pointer to the family name or 0L
addrin[3]        style_name     Pointer to den style name or 0L

Outputs:

contrl[2]        1              Entries in intout
contrl[4]        0              Entries in addrout

intout[0]        ret            0: Error 1: All OK



2.5.10 FONT SELECTOR - GET FONT INFO (AES 184, 3)
-------------------------------------------------


Declaration:
WORD fnts_get_info( FNT_DIALOG *fnt_dialog, LONG id,
                          WORD *mono, WORD *outline );

Call:
index = fnts_get_info( fnt_dialog, id, &mono, &outline );

Variable         Argument            Meaning
Inputs:

contrl[0]        184                 fnts_get
contrl[1]        3                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         3                   fnts_get_info
intin[1/2]       id                  Font ID

addrin[0]        fnt_dialog          Pointer to management structure

Outputs:

contrl[2]        3                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        index               0: Error
                                    >0: Index for vqt_name()
intout[1]        mono                Flag for mono-spaced font
intout[2]        outline             Flag for vector font



2.5.11 FONT SELECTOR - ADD USER FONTS (AES 185, 0)
--------------------------------------------------

With ADD USER FONTS a program can add its own user fonts to those
displayed by the font selector. The IDs of these fonts must be higher 
than 65535. In addition the pointer to a display function must be 
entered into the structure element <display>.


Declaration:
WORD fnts_add( FNT_DIALOG *fnt_dialog, FNTS_ITEM *user_fonts );

Call:
ret = WORD fnts_add( fnt_dialog, user_fonts );

Variable         Argument            Meaning
Inputs:

contrl[0]        185                 fnts_set
contrl[1]        1                   Entries in intin
contrl[3]        2                   Entries in addrin

intin[0]         0                   fnts_add

addrin[0]        fnt_dialog          Pointer to management structure
addrin[1]        user_fonts          Pointer to user fonts

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        ret                 0: Error   1: All OK

Declaration of FNTS_ITEM:

typedef struct _fnts_item
{
   struct   _fnts_item  *next;
              /* Pointer to the next font or 0L (end of the list) */
   UTXT_FN  display;
              /* Pointer to the display function for the user fonts */
   LONG     id;            /* Font ID, >= 65536 for user fonts */
   WORD     index;         /* Must be 0, as not a VDI font */
   BYTE     mono;          /* Flag for mono-spaced font */
   BYTE     outline;       /* Flag for vector font */
   WORD     npts;          /* Number of predefined point sizes */
   BYTE     *full_name;    /* Pointer to the complete name */
   BYTE     *family_name;  /* Pointer to the family name */
   BYTE     *style_name;   /* Pointer to the style name */
   BYTE     *pts;          /* Pointer to field with point sizes */
   LONG     reserved[4];   /* Reserved, must be 0 */
} FNTS_ITEM;

typedef void (cdecl *UTXT_FN)( WORD x, WORD y, WORD *clip_rect,
                               LONG id, LONG pt, LONG ratio, BYTE *string );



2.5.12 FONT SELECTOR - REMOVE USER FONTS (AES 185, 1)
-----------------------------------------------------

REMOVE USER FONTS removes the fonts installed with ADD FONTS from 
the binding. If a program's user fonts have been installed, then 
fnts_remove() must be called before fnts_delete().


Declaration:
void fnts_remove( FNT_DIALOG *fnt_dialog );

Call:
fnts_remove( fnt_dialog );

Variable         Argument            Meaning
Inputs:

contrl[0]        185                 fnts_set
contrl[1]        1                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         1                   fnts_remove

addrin[0]        fnt_dialog          Pointer to management structure

Outputs:

contrl[2]        0                   Entries in intout
contrl[4]        0                   Entries in addrout



2.5.13 FONT SELECTOR - UPDATE WINDOW (AES 185, 2)
-------------------------------------------------


Declaration:
WORD fnts_update( FNT_DIALOG *fnt_dialog, WORD button_flags,
                               LONG id, LONG pt, LONG ratio );

Call:
result = fnts_update( fnt_dialog, 0x3f0f, id, pt, ratio );

Variable         Argument            Meaning
Inputs:

contrl[0]        185                 fnts_set
contrl[1]        8                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         2                   fnts_update
intin[1]         button_flags        Flags for supported buttons
intin[2/3]       id                  Font ID
intin[4/5]       pt                  Height in 1/65536 point
intin[6/7]       ratio               Width/height ratio in 1/65536

addrin[0]        fnt_dialog          Pointer to management structure

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        result


Description of <result>:


	-1:	Function not present
	 0:	Error (insufficient memory), the font selector must then be 
	 	closed with fnts_close().
	 1:	All OK


Description of <button_flags>:

#define FNTS_SNAME     0x01  /* Select checkbox for the names */
#define FNTS_SSTYLE    0x02  /* Select checkbox for the style */
#define FNTS_SSIZE     0x04  /* Select checkbox for the height */
#define FNTS_SRATIO    0x08  /* Select checkbox for the width/height 
						  ratio */

#define FNTS_CHNAME   0x0100  /* Display checkbox for the names */
#define FNTS_CHSTYLE  0x0200  /* Display checkbox for the style */
#define FNTS_CHSIZE   0x0400  /* Display checkbox for the height */
#define FNTS_CHRATIO  0x0800  /* Display checkbox for the width/height
                                 ratio */
#define FNTS_RATIO    0x1000  /* Width/height ratio adjustable */
#define FNTS_BSET     0x2000  /* Button "setting" selectable */
#define FNTS_BMARK    0x4000  /* Button "marking" selectable */


Note: This function was not present in older versions of WDIALOG. 
The binding ensures that in that case intout[0] returns -1.



2.5.14 FONT SELECTOR - HANDLE EVENT (AES 186)
---------------------------------------------

HANDLE EVENT evaluates the passed  EVNT structure and internally calls
wdlg_evnt(). If one of the exit buttons ("Cancel", "OK", "Set", "Mark" 
or "Options") was activated  the function returns 0 and the button that 
the user has selected is returned in button.


Declaration:
WORD fnts_evnt( FNT_DIALOG *fnt_dialog, EVNT *events, WORD *button,
               WORD *check_boxes, LONG *id, LONG *pt, LONG *ratio );

Call:
cont = fnts_evnt( fnt_dialog, &events, &button, &check_boxes,
                                            &id, &pt, &ratio );

Variable         Argument            Meaning
Inputs:

contrl[0]        186                 fnts_evnt
contrl[1]        0                   Entries in intin
contrl[3]        2                   Entries in addrin

addrin[0]        fnt_dialog          Pointer to management structure
addrin[1]        events              Pointer to EVNT structure

Outputs:

contrl[2]        9                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        cont                0: Exit button selected
                                     1: Nothing happened
intout[1]        button              Selected button (or 0)
intout[2]        check_boxes         Status of the checkboxes
intout[3/4]      id                  ID of the selected font
intout[5/6]      pt                  Height in 1/65536 point
intout[7/8]      ratio               Width/height ratio

Description of <check_boxes>:

#define  FNTS_SNAME     0x01   /* Checkbox for the names selected */
#define  FNTS_SSTYLE    0x02   /* Checkbox for the style selected */
#define  FNTS_SSIZE     0x04   /* Checkbox for the height selected */
#define  FNTS_SRATIO    0x08   /* Checkbox for the width/height ratio
                                  selected */



2.5.15 FONT SELECTOR - DO (AES 187)
-----------------------------------

fnts_do() is the counterpart to fnts_open()/fnts_evnt()/fnts_close(). 
This function opens a modal dialog and only returns to the caller when 
one of the exit buttons ("Cancel", "OK", "Set", "Mark" or "Options") 
was activated.


Declaration:
WORD fnts_do( FNT_DIALOG *fnt_dialog, WORD button_flags,
              LONG id_in, LONG pt_in, LONG ratio_in,
              WORD *check_boxes, LONG *id, LONG *pt, LONG *ratio );

Call:
button = fnts_do( fnt_dialog, button_flags, id_in, pt_in, ratio_in,
                                 &check_boxes, &id, &pt, &ratio );

Variable         Argument            Meaning
Inputs:

contrl[0]        187                 fnts_do
contrl[1]        7                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         button_flags
intin[1/2]       id_in
intin[3/4]       pt_in
intin[5/6]       ratio_in

addrin[0]        fnt_dialog          Pointer to management structure

Outputs:

contrl[2]        8                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        button              Selected button (or 0)
intout[1]        check_boxes         Status of the checkboxes
intout[2/3]      id                  ID of the selected font
intout[4/5]      pt                  Height in 1/65536 point
intout[6/7]      ratio               Width/height ratio



2.6 Print dialogs
=================

+---------------------------+--------------------------------------------+
| pdlg_create()		   |	Initialise print dialog, allocate memory   |
| pdlg_open()			   |	Open selection dialog in window            |
| pdlg_close()			   |	Close window                               |
| pdlg_delete()		   |	Free memory                                |
+---------------------------+--------------------------------------------+
| pdlg_get_setsize()	   |	Get size of the structure                  |
+---------------------------+--------------------------------------------+
| pdlg_add_printers()	   |	Add application's printers                 |
| pdlg_remove_printers()	   |	Remove application's printers              |
| pdlg_update()		   |	Update window title                        |
| pdlg_add_sub_dialogs()	   |	Add application's sub-dialogs              |
| pdlg_remove_sub_dialogs() |	Remove application's sub-dialogs           |
| pdlg_new_settings()	   |	Return pointer to initialised printer      |
|					   |	settings							   | 
| pdlg_free_settings()	   |	Free memory used for printer settings      |
| pdlg_dflt_settings()	   |	Initialise memory region with printer      | 
|					   |	settings                                   |
| pdlg_validate_settings()  |	Validate printer settings                  |
| pdlg_use_settings()	   |	Validate and adopt printer settings        |
+---------------------------+--------------------------------------------+
| pdlg_evnt()			   |	Manage events for dialog in window         |
| pdlg_do()			   |	Display modal dialog                       |
+---------------------------+--------------------------------------------+



2.6.1 Calling procedure for print dialog in a window
----------------------------------------------------


Program start:
   .
   .                         pdlg_create()
   .
   .
   .
Calling the print dialog:    pdlg_open()
   .
   .
   .
Event loop:                  pdlg_evnt()
   .                             .
   .                             .
   .                             .
   .                             .
Closing of the print dialog: pdlg_close()
   .
   .
   .
   .                         pdlg_delete()
   .
Program end:



2.6.2 Calling procedure for modal print dialog
----------------------------------------------


Program start:
   .
   .                       pdlg_create()
   .
   .
   .
Calling the print dialog:  pdlg_do()
   .
   .
   .
   .                       pdlg_delete()
   .
Program end:



2.6.3 PRINT DIALOG - CREATE (AES 200)
-------------------------------------

CREATE initialises the print dialog. <dialog_flags> passes whether the 
dialog is to be displayed in 3D-look or not. On calling the function a 
scan will be made for the printer drivers present and memory will be 
allocated for the resource.


Declaration:
PRN_DIALOG *pdlg_create( int16 dialog_flags )

Call:
prn_dialog = pdlg_create( PDLG_3D );

Variable         Argument            Meaning
Inputs:

contrl[0]        200                 pdlg_create
contrl[1]        1                   Entries in intin
contrl[3]        0                   Entries in addrin

intin[0]         flags               Only 3D-flag at present

Outputs:

contrl[2]        0                   Entries in intout
contrl[4]        1                   Entries in addrout

addrout[0]       prn_dialog          Pointer to management structure

Description of <dialog_flags>:

#define  PDLG_3D     1               /* Display selection in 3D-look */



2.6.4 PRINT DIALOG - DELETE (AES 201)
-------------------------------------

This function releases the memory for the print dialog.


Declaration:
WORD pdlg_delete( PRN_DIALOG *prn_dialog );

Call:
pdlg_delete( prn_dialog );

Variable         Argument            Meaning
Inputs:

contrl[0]        201                 pdlg_delete
contrl[1]        0                   Entries in intin
contrl[3]        1                   Entries in addrin

addrin[0]        prn_dialog          Pointer to management structure

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        1



2.6.5 PRINT DIALOG - OPEN WINDOW (AES 202)
------------------------------------------

OPEN WINDOW opens a window with the print dialog. The handle of the 
window will be returned if no error has arisen. In case of error the 
return value is 0. The structure <settings> contains the printer 
settings, which should be saved with each document. If no settings exist 
for a document yet, one can either create them with pdlg_new_settings() 
(the memory block belongs to the system) or the application can call 
Malloc() and subsequently pdlg_dflt_settings() to initialise the memory.

<option_flags> contains information, among other things, whether the 
dialog is to be displayed as a settings (PDLG_PREFS) or print dialog 
(PDLG_PRINT). In addition the flags PDLG_ALWAYS_COPIES, PDLG_ALWAYS_ORIENT 
and PDLG_ALWAYS_SCALE can ensure that the number of copies, landscape 
printing and scaling options are offered even when the driver does not 
support them, so that the application has to output the page rotated to 
the landscape format, for instance. PDLG_EVENODD makes the buttons for 
even/odd pages selectable.


Declaration:
WORD pdlg_open( PRN_DIALOG *prn_dialog, PRN_SETTINGS *settings,
                BYTE *document_name, WORD option_flags, WORD x, WORD y );

Call:
whdl = pdlg_open( prn_dialog, settings, "Untitled", PDLG_PREFS, -1, -1 );

Variable         Argument         Meaning
Inputs:

contrl[0]        202              pdlg_open
contrl[1]        3                Entries in intin
contrl[3]        3                Entries in addrin

intin[0]         option_flags
intin[1]         x                X-coordinates of the window or -1 
                                  (centred)
intin[2]         y                Y-coordinates of the window or -1
                                  (centred)

addrin[0]        prn_dialog       Pointer to management structure
addrin[1]        settings         Printer settings
addrin[2]        document_name    Document name

Outputs:

contrl[2]        1                Entries in intout
contrl[4]        0                Entries in addrout

intout[0]        whdl             Handle of the window or 0 (error)


Description of <option_flags>:

#define PDLG_PREFS          0x0000  /* Display settings dialog */
#define PDLG_PRINT          0x0001  /* Display print dialog */

#define PDLG_ALWAYS_COPIES  0x0010  /* Always offer No. of copies */
#define PDLG_ALWAYS_ORIENT  0x0020  /* Always offer landscape format */
#define PDLG_ALWAYS_SCALE   0x0040  /* Always offer scaling */

#define PDLG_EVENODD        0x0100  /* Offer option for even and odd pages */


Description of <settings>:

/* <page_flags> */
#define  PG_EVEN_PAGES  0x0001  /* Only output pages with even page numbers */
#define  PG_ODD_PAGES   0x0002  /* Only output pages with odd page numbers */

/* <first_page/last_page> */
#define  PG_MIN_PAGE    1
#define  PG_MAX_PAGE    9999

/* <orientation> */
#define  PG_UNKNOWN     0x0000  /* Orientation unknown and not adjustable */
#define  PG_PORTRAIT    0x0001  /* Output page in portrait format */
#define  PG_LANDSCAPE   0x0002  /* Output page in landscape format */


typedef struct _prn_settings
{
   LONG  magic;            /* 'pset' */
-->LONG  length;           /* Structure length */
   LONG  format;           /* Structure type */
   LONG  reserved;

-->LONG  page_flags;       /* Flags, inc. even pages, odd pages */
-->WORD  first_page;       /* First page to be printed */
-->WORD  last_page;        /* Last page to be printed */
-->WORD  no_copies;        /* Number of copies */
-->WORD  orientation;      /* Orientation */
-->LONG  scale;            /* Scaling: 0x10000L corresponds to 100% */

-->WORD  driver_id;        /* VDI device number */
   WORD  driver_type;      /* Type of driver set */
   LONG  driver_mode;      /* Flags, inc. for background printing */
   LONG  reserved1;
   LONG  reserved2;

   LONG  printer_id;       /* Printer number */
   LONG  mode_id;          /* Mode number */
   WORD  mode_hdpi;        /* Horizontal resolution in dpi */
   WORD  mode_vdpi;        /* Vertical resolution in dpi */
   LONG  quality_id;       /* Print mode (hardware-dependent quality,
                              e.g. Microweave or Econofast) */

   LONG  color_mode;       /* Colour mode */
   LONG  plane_flags;      /* Flags for colour planes to be output
                              (e.g. cyan only) */
   LONG  dither_mode;      /* Dither process */
   LONG  dither_value;     /* Parameter for the dither process */

   LONG  size_id;          /* Paper format */
   LONG  type_id;          /* Paper type (normal, glossy) */
   LONG  input_id;         /* Paper feed channel */
   LONG  output_id;        /* Paper output channel */

   LONG  contrast;         /* Contrast: 0x10000L corresponds to the
                              normal setting */
   LONG  brightness;       /* Brightness: 0x1000L corresponds to the
                              normal setting */
   LONG  reserved3;
   LONG  reserved4;

   LONG  reserved5;
   LONG  reserved6;
   LONG  reserved7;
   LONG  reserved8;

   BYTE  device[128];      /* File name to be printed */

#ifdef __PRINTING__
   TPrint   mac_settings;  /* Settings of the Mac printer driver */
#else
   struct
   {
      UBYTE inside[120];
   } mac_settings;
#endif

} PRN_SETTINGS;


The structure items marked with --> can be read by the application.
All other entries should not be accessed. Data such as the printer 
resolution or colour planes, for instance, should not be taken from the 
settings structure but requested from the printer at the start of printing 
(it is possible, for instance, that the printer driver is forced by a 
shortage of memory to reduce the print resolution below the value entered 
in PRN_SETTINGS).



2.6.6 PRINT DIALOG - CLOSE WINDOW (AES 203)
-------------------------------------------

CLOSE WINDOW closes the window of the print dialog. <x> and <y> return 
the last window position.


Declaration:
WORD pdlg_close( PRN_DIALOG *prn_dialog, WORD *x, WORD *y );

Call:
pdlg_close( prn_dialog, &x, &y );

Variable         Argument            Meaning
Inputs:

contrl[0]        203                 pdlg_close
contrl[1]        0                   Entries in intin
contrl[3]        1                   Entries in addrin

addrin[0]        prn_dialog          Pointer to management structure

Outputs:

contrl[2]        3                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        1
intout[1]        x                   X-coordinates of the window
intout[2]        y                   Y-coordinates of the window

 

2.6.7 PRINT DIALOG - GET SETTING STRUCTURE SIZE (AES 204, 0)
------------------------------------------------------------

This function returns the length of the PRN_SETTINGS structure.


Declaration:
LONG pdlg_get_setsize( void );

Call:
length = pdlg_get_setsize();

Variable         Argument            Meaning
Inputs:

contrl[0]        204                 pdlg_get
contrl[1]        1                   Entries in intin
contrl[3]        0                   Entries in addrin

intin[0]         0                   pdlg_get_setsize

Outputs:

contrl[2]        2                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0..1]     length              Structure length in bytes

 

2.6.8 PRINT DIALOG - ADD PRIVATE PRINTERS (AES 205, 0)
------------------------------------------------------

With ADD PRIVATE PRINTERS a program can add its own private printer 
descriptions to the dialog. <drv_info> contains a pointer to a list of 
available printers and dither processes. The driver number should be 
set to 0x7fff to differentiate the private driver from the OS-drivers.


Declaration:
WORD pdlg_add_printers( PRN_DIALOG *prn_dialog, DRV_INFO *drv_info );

Call:
ret = pdlg_add_printers( prn_dialog, &drv_info );

Variable         Argument            Meaning
Inputs:

contrl[0]        205                 pdlg_set
contrl[1]        1                   Entries in intin
contrl[3]        2                   Entries in addrin

intin[0]         0                   pdlg_add_driver

addrin[0]        prn_dialog          Pointer to management structure
addrin[1]        driver

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        ret                 0: Error    1: All OK


Structure description:

typedef struct
{
   LONG        magic;               /* 'pdnf' */
   LONG        length;              /* Structure length */
   LONG        format;              /* Data format */
   LONG        reserved;            /* Reserved */

   WORD        driver_id;           /* Driver number for the VDI */
   WORD        driver_type;         /* Driver type */
   LONG        reserved1;
   LONG        reserved2;
   LONG        reserved3;

   PRN_ENTRY   *printers;           /* List of printers belonging to 
                                       the driver */
   DITHER_MODE *dither_modes;       /* List of dither processes 
                                       supported by the driver */
   LONG        reserved4;
   LONG        reserved5;

   LONG        reserved6;
   LONG        reserved7;
   LONG        reserved8;
   LONG        reserved9;

   BYTE        device[128];         /* Printer driver output file */

} DRV_INFO;

typedef struct _dither_mode
{
   struct _dither_mode  *next;
   LONG        length;              /* Structure length */
   LONG        format;              /* Data format */
   LONG        reserved;            /* Reserved */

   LONG        dither_id;           /* Dither ID */
   LONG        color_modes;         /* Colour depths supported */

   LONG        reserved1;
   LONG        reserved2;

   BYTE        name[32];            /* Name of the dither process */
} DITHER_MODE;

typedef struct _prn_entry           /* Device description */
{
   struct _prn_entry *next;         /* Pointer to next device description */
   LONG        length;              /* Structure length */
   LONG        format;              /* Data format */
   LONG        reserved;            /* Reserved */

   WORD        driver_id;           /* Driver ID */
   WORD        driver_type;         /* Driver type */
   LONG        printer_id;          /* Printer ID */
   LONG        printer_capabilities; /* Printer capabilities */
   LONG        reserved1;

   LONG        flags;
   struct _pdlg_sub  *sub_dialogs;  /* Pointer to the list of sub-dialogs 
                                       for this printer */
   PRN_SWITCH  setup_panel;         /* Initialise sub-dialog at printer 
                                       change */
   PRN_SWITCH  close_panel;         /* Close sub-dialog at printer change */

   PRN_MODE    *modes;              /* List of available resolutions */
   MEDIA_SIZE  *papers;             /* List of available paper formats */
   PRN_TRAY    *input_trays;        /* List of feed trays */
   PRN_TRAY    *output_trays;       /* List of output trays */

   BYTE        name[32];            /* Name of the printer */
} PRN_ENTRY;

/* old_printer can also be 0L */
typedef LONG  (cdecl *PRN_SWITCH)( struct _drv_entry *drivers, 
          struct _prn_settings *settings, struct _prn_entry *old_printer, 
          struct _prn_entry *new_printer );

#define  PRN_STD_SUBS   0x0001

typedef struct _prn_mode            /* Description of a print mode */
{
   struct _prn_mode *next;          /* Pointer to the next print mode */

   LONG        mode_id;             /* Mode ID (index within the file) */
   WORD        hdpi;                /* Horizontal resolution in dpi */
   WORD        vdpi;                /* Vertical resolution in dpi */
   LONG        mode_capabilities;   /* Mode capabilities */

   LONG        color_capabilities;  /* Colour capabilities */
   LONG        dither_flags;        /* Flags specifying whether the corres-
                                       ponding colour mode is accessible
                                       with or without dithering */
   MEDIA_TYPE  *paper_types;        /* Suitable paper types */
   LONG        reserved;

   BYTE        name[32];            /* Mode name */
} PRN_MODE;

typedef struct _media_type          /* Description of a paper type/print 
                                       medium */
{
   struct _media_type   *next;

   LONG        type_id;             /* Paper format type ID */
   BYTE        name[32];            /* Name of the paper format */
} MEDIA_TYPE;

typedef struct _media_size          /* Description of a paper format */
{
   struct _media_size   *next;

   LONG        size_id;             /* Paper format size ID */
   BYTE        name[32];            /* Name of the paper format */
} MEDIA_SIZE;

typedef struct _prn_tray            /* Description of a feed/output tray */
{
   struct _prn_tray  *next;

   LONG        tray_id;             /* Number of the feed or output tray */
   BYTE        name[32];            /* Name of the tray */
} PRN_TRAY;



2.6.9 PRINT DIALOG - REMOVE PRIVATE PRINTERS (AES 205, 1)
---------------------------------------------------------

REMOVE PRIVATE PRINTERS removes the printers installed with ADD PRIVATE 
PRINTERS from the binding. pdlg_remove_printers() must be called before 
pdlg_delete().


Declaration:
WORD pdlg_remove_printers( PRN_DIALOG *prn_dialog );

Call:
pdlg_remove_printers( prn_dialog );

Variable         Argument            Meaning
Inputs:

contrl[0]        205                 pdlg_set
contrl[1]        1                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         1                   pdlg_remove_driver

addrin[0]        prn_dialog          Pointer to management structure

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]

 

2.6.10 PRINT DIALOG - UPDATE WINDOW (AES 205, 2)
------------------------------------------------

This function sets a new window name. It should be called when the 
window dialog lies in the background and the user tops a new document 
window.


Declaration:
WORD pdlg_update( PRN_DIALOG *prn_dialog, BYTE *document_name );

Call:
pdlg_update( prn_dialog, "Untitled #1" );

Variable         Argument            Meaning
Inputs:

contrl[0]        205                 pdlg_set
contrl[1]        1                   Entries in intin
contrl[3]        3                   Entries in addrin

intin[0]         2                   pdlg_update

addrin[0]        prn_dialog          Pointer to management structure
addrin[1]        0                   Reserved (must be 0!)
addrin[2]        document_name       New document name

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        0/1                 0: Error
                                     1: All OK


2.6.11 PRINT DIALOG - ADD PRIVATE DIALOGS (AES 205, 3)
------------------------------------------------------

With pdlg_add_sub_dialogs() an application can add its custom 
sub-dialogs to the printer dialog to offer special print options (e.g. 
watermarks, background images etc.).


Declaration:
WORD pdlg_add_sub_dialogs( PRN_DIALOG *prn_dialog,
                           PDLG_SUB *sub_dialog );

Call:
ret = pdlg_add_sub_dialogs( prn_dialog, sub_dialogs );

Variable         Argument            Meaning
Inputs:

contrl[0]        205                 pdlg_set
contrl[1]        1                   Entries in intin
contrl[3]        2                   Entries in addrin

intin[0]         3                   pdlg_add_sub_dialog

addrin[0]        prn_dialog          Pointer to management structure
addrin[1]        sub_dialogs         List of sub-dialogs

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        ret                 0: Error   1: All OK


Note:

The hooking in of an application's own dialogs is demonstrated in the 
sample programs PDLGSMP3.C and PDLGSMP4.C.

Structure description:

#define  PDLG_CHG_SUB   0x80000000L
#define  PDLG_IS_BUTTON 0x40000000L

#define  PDLG_PREBUTTON 0x20000000L
#define  PDLG_PB_OK     1
#define  PDLG_PB_CANCEL 2
#define  PDLG_PB_DEVICE 3

#define  PDLG_BUT_OK    ( PDLG_PREBUTTON + PDLG_PB_OK )
#define  PDLG_BUT_CNCL  ( PDLG_PREBUTTON + PDLG_PB_CANCEL )
#define  PDLG_BUT_DEV   ( PDLG_PREBUTTON + PDLG_PB_DEVICE )

typedef  int32 (cdecl *PDLG_INIT)( struct _prn_settings *settings, 
                                   struct _pdlg_sub *sub );
typedef  int32 (cdecl *PDLG_HNDL)( struct _prn_settings *settings, 
                                   struct _pdlg_sub *sub, int16 exit_obj );
typedef  int32 (cdecl *PDLG_RESET)( struct _prn_settings *settings, 
                                    struct _pdlg_sub *sub );

typedef struct _pdlg_sub      /* Sub-dialog for setting device */
{
   struct _pdlg_sub *next;    /* Pointer to the successor in the list */
   int32       length;        /* Structure length */
   int32       format;        /* Data format */
   int32       reserved;      /* Reserved */

   void        *drivers;      /* Only for internal dialogs */
   int16       option_flags;  /* Flags, inc. PDLG_PRINTING, PDLG_PREFS */
   int16       sub_id;        /* Sub-dialog ID, entered for global 
                                 sub-dialogs of pdlg_add() */
   DIALOG      *dialog;       /* Pointer to the structure of the window
                                 dialog or 0L */
   OBJECT      *tree;         /* Pointer to the assembled object tree */
   int16       index_offset;  /* Index offset of the sub-dialog */
   int16       reserved1;
   int32       reserved2;
   int32       reserved3;
   int32       reserved4;

   PDLG_INIT   init_dlg;      /* Initialisation function */
   PDLG_HNDL   do_dlg;        /* Handling function */
   PDLG_RESET  reset_dlg;     /* Reset function */
   int32       reserved5;

   OBJECT      *sub_icon;     /* Pointer to the icon for the list box */
   OBJECT      *sub_tree;     /* Pointer to the object tree of the 
                                 sub-dialog */
   int32       reserved6;
   int32       reserved7;

   int32       private1;      /* Dialog's private information */
   int32       private2;
   int32       private3;
   int32       private4;

} PDLG_SUB;



2.6.12 PRINT DIALOG - REMOVE PRIVATE DIALOGS (AES 205, 4)
---------------------------------------------------------

... removes the application's custom sub-dialogs.


Declaration:
WORD pdlg_remove_sub_dialogs( PRN_DIALOG *prn_dialog );

Call:
pdlg_remove_sub_dialogs( prn_dialog );

Variable         Argument            Meaning
Inputs:

contrl[0]        205                 pdlg_set
contrl[1]        1                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         4                   pdlg_remove_sub_dialogs

addrin[0]        prn_dialog          Pointer to management structure

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]



2.6.13 PRINT DIALOG - NEW DEFAULT SETTINGS (AES 205, 5)
-------------------------------------------------------

Memory for printer settings is allocated, the structure is initialised 
and returned.


Declaration:
PRN_SETTINGS *pdlg_new_settings( PRN_DIALOG *prn_dialog );

Call:
settings = pdlg_new_settings( prn_dialog );

Variable         Argument            Meaning
Inputs:

contrl[0]        205                 pdlg_set
contrl[1]        1                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         5                   pdlg_new_settings

addrin[0]        prn_dialog          Pointer to management structure

Outputs:

contrl[2]        0                   Entries in intout
contrl[4]        1                   Entries in addrout

addrout[0]       settings            Printer settings



2.6.14 PRINT DIALOG - FREE SETTINGS (AES 205, 6)
------------------------------------------------

Releases the memory allocated with pdlg_new_settings().


Declaration:
WORD pdlg_free_settings( PRN_SETTINGS *settings );

Call:
pdlg_free_settings( settings )

Variable         Argument            Meaning
Inputs:

contrl[0]        205                 pdlg_set
contrl[1]        1                   Entries in intin
contrl[3]        1                   Entries in addrin

intin[0]         6                   pdlg_free_settings

addrin[0]        settings            Printer settings

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]



2.6.15 PRINT DIALOG - DEFAULT SETTINGS (AES 205, 7)
---------------------------------------------------

Initialises the structure to which <settings> points. 
(Structure length can be found with pdlg_get_setsize().


Declaration:
WORD pdlg_dflt_settings( PRN_DIALOG *prn_dialog,
                         PRN_SETTINGS *settings );

Call:
pdlg_dflt_settings( prn_dialog, settings );

Variable         Argument            Meaning
Inputs:

contrl[0]        205                 pdlg_set
contrl[1]        1                   Entries in intin
contrl[3]        2                   Entries in addrin

intin[0]         7                   pdlg_dflt_settings

addrin[0]        prn_dialog          Pointer to management structure
addrin[1]        settings            Printer settings

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        1



2.6.16 PRINT DIALOG - VALIDATE SETTINGS (AES 205, 8)
----------------------------------------------------

Validate the printer settings and if necessary correct the sctructure 
contents.


Declaration:
WORD pdlg_validate_settings( PRN_DIALOG *prn_dialog,
					    PRN_SETTINGS *settings );

Call:
pdlg_validate_settings( prn_dialog, settings );

Variable         Argument            Meaning
Inputs:

contrl[0]        205                 pdlg_set
contrl[1]        1                   Entries in intin
contrl[3]        2                   Entries in addrin

intin[0]         8                   pdlg_validate_settings

addrin[0]        prn_dialog          Pointer to management structure
addrin[1]        settings            Printer settings

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        0/1                 0: Error    1: All OK


 
2.6.17 PRINT DIALOG - USE SETTINGS (AES 205, 9)
-----------------------------------------------

This function should be called if a program wants to print immediately 
and it is not possible to call pdlg_do() or pdlg_open() and pdlg_evnt() 
(e.g. Calamus-print dialogs).
The passed printer settings will be validated (and saved for old drivers).


Declaration:
WORD pdlg_use_settings( PRN_DIALOG *prn_dialog,
                        PRN_SETTINGS *settings );

Call:
pdlg_use_settings( prn_dialog, settings );

Variable         Argument            Meaning
Inputs:

contrl[0]        205                 pdlg_set
contrl[1]        1                   Entries in intin
contrl[3]        2                   Entries in addrin

intin[0]         9                   pdlg_use_settings

addrin[0]        prn_dialog          Pointer to management structure
addrin[1]        settings            Printer settings

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        0/1                 0: Error    1: All OK

 

2.6.18 PRINT DIALOG - HANDLE EVENT (AES 206)
--------------------------------------------

HANDLE EVENT evaluates the passed EVNT structure and calls wdlg_evnt() 
internally. If one of the exit buttons was activated ("Cancel", "OK", 
"Set", "Mark" or "Options") the function returns a 0 and the button that 
the user has selected is returned in <button>. If the dialog was confirmed, 
then the new printer settings are returned in <settings>.


Declaration:
WORD pdlg_evnt( PRN_DIALOG *prn_dialog, PRN_SETTINGS *settings,
                                 EVNT *events, WORD *button );

Call:
cont = pdlg_evnt( prn_dialog, settings, &events, &button );

Variable         Argument            Meaning
Inputs:

contrl[0]        206                 pdlg_evnt
contrl[1]        0                   Entries in intin
contrl[3]        3                   Entries in addrin

addrin[0]        prn_dialog          Pointer to management structure
addrin[1]        settings            Printer settings
addrin[2]        events              Pointer to EVNT structure

Outputs:

contrl[2]        2                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        cont                0: Exit button selected
                                     1: Nothing happened
intout[1]        button              Selected button (or 0)


Description of <button>:

#define  PDLG_CANCEL 1  /* "Cancel" was selected */
#define  PDLG_OK     2  /* "OK" was pressed */

Description of <set tings>:
see pdlg_open...
 


2.6.19 PRINT DIALOG - DO (AES 207)
----------------------------------

pdlg_do() is the counterpart to pdlg_open()/pdlg_evnt()/pdlg_close(). This 
function opens a modal dialog and only returns to the caller when one of 
the exit buttons has been activated ("Cancel", "OK" ).


Declaration:
WORD pdlg_do( PRN_DIALOG *prn_dialog, PRN_SETTINGS *settings,
                   BYTE *document_name, WORD option_flags );

Call:
button = pdlg_do( prn_dialog, settings, "Unnamed", PDLG_PRINT );

Variable         Argument            Meaning
Inputs:

contrl[0]        207                 pdlg_do
contrl[1]        1                   Entries in intin
contrl[3]        3                   Entries in addrin

intin[0]         option_flags

addrin[0]        prn_dialog          Pointer to management structure
addrin[1]        settings            Printer settings
addrin[2]        document_name       Document name

Outputs:

contrl[2]        1                   Entries in intout
contrl[4]        0                   Entries in addrout

intout[0]        button              Selected button (or 0)


Description of <option_flags>:

#define PDLG_PREFS          0x0000  /* Display settings dialog */
#define PDLG_PRINT          0x0001  /* Display print dialog */

#define PDLG_ALWAYS_COPIES  0x0010  /* Always offer No. of copies */
#define PDLG_ALWAYS_ORIENT  0x0020  /* Always offer landscape format */
#define PDLG_ALWAYS_SCALE   0x0040  /* Always offer scaling */

#define PDLG_EVENODD        0x0100  /* Offer option for even and odd pages */


Description of <button>:

#define  PDLG_CANCEL 1              /* "Cancel" was selected */
#define  PDLG_OK     2              /* "OK" was pressed */

Description of <settings>:
see pdlg_open...
 


2.7 Conversion of extended object types
=======================================

The ADAPTRSC.C module makes a number of useful functions available:

    It returns information about the AES functions present.

    It adapts RSC files to overcome the (ugly) MultiTOS peculiarity
	of enlarging 3D-objects above the dimensions specified in the OBJECT
	structure.

    It adapts (as far as it's possible automatically) RSC files from 
	3D to 2D.

    It automatically generates, when necessary, userdef functions 
	for extended MagiC 3-objects: Underlined headings, group frames,
	radio buttons and checkboxes (with adjacent string).
     
The module occupies some 2 kB of memory.

 

A 	Function and structure definitions
***************************************

MT_AES.H

 

B 	Binding
************

MT_AES.LIB



C 	Sample source texts
************************

    FNT_SMPL.C, FNT_SMP2.C, FNT_SMP3.C,

    PDLGSMP1.C, PDLGSMP2.C, PDLGSMP3.C, PDLGSMP4.C,

    WDLG_SMP.C,

    XOBJ_SMP.C,

    ADAPTRSC.C











 