Click above to get retro games delivered to your door ever month!

@ ID ... <ControlType>
Use a specified type of control in a dialog
------------------------------------------------------------------------------

Syntax
#include "windows.ch"
#include "topclass.ch"   --or--   #define  NO_C4WCLASS
#include "commands.ch"
@ ID  <nId>  [ OBJECT <oObj> ]
     <ControlType>
     [ <cCmd> ]
     [ TEXT | TITLE <cTitle> ]
     [ INITIAL | ITEMS <xInit> ]
     [ ACTION <a> ]
     [ VALID <v> ]
     [ AT <x>, <y> ]  [ SIZE <w>, <h> ]
     [ FROM <x>, <y>  TO <r>, <b> ]
     [ WIDTH <w>  HEIGHT <h> ]
     [ STYLE <nStyle> ]
     [ IN  [ DIALOG ] <oDlg> ]

Arguments
<nId> is the numeric identifier (usually a small non-zero
integer less than 30000), used to identify the control.
Dialog editors such as that in the Clip-4-Win Toolkit usually
assign id's for you, and can be asked to generate a header
file with #defines.

For a resource dialog, the id in your Clipper code must match
the id in the resource, otherwise the control's window handle
(hWnd) will not be found, and your code is likely to produce
strange results, if any.

<oObj> specifies a variable to receive the control object.
This is ignored for a non-OO application (i.e. if NO_C4WCLASS
is defined).

<ControlType> indicates one of the types of control which can
be specified for this command.  The types include:

     3DBORDER
     3DFRAME
     BITMAP BUTTON
     BITMAP FILE
     BITMAP RESOURCE
     BLACKFRAME
     BLISTBOX
     BUTTON
     BUTTON BITMAP
     BUTTON SPIN
     CENTERTEXT
     CHECKBOX
     COMBOBOX
     CONTROL
     DROPDOWNLIST
     EDIT
     GET
     GRAYFRAME
     GROUPBOX
     HORIZ SCROLLBAR
     ICON
     LEFTTEXT
     LISTBOX
     MULTILINE EDIT
     PROGRESSBAR
     RADIOBUTTON
     RAISEDFRAME
     RIGHTTEXT
     SAY
     SAYCENTER
     SAYLEFT
     SAYRIGHT
     SCROLLBAR
     SPIN BUTTON
     SSCONTROL
     SUNKENFRAME
     VBX
     VERT SCROLLBAR
     WHITEFRAME

Refer to the individual commands for more detail, and also to
COMMANDS.CH.

<cCmd> is a message (method) name (for an OO application) or a
function name (if NO_C4WCLASS is defined).  If this control
sends messages to the dialog, Clip-4-Win will either execute
the specified message in the dialog (if OO) or call the
function.

This mechanism where the message is sent to (executed in) the
dialog can be described as "smart dialogs, dumb controls".  If
you want to change this, refer to the OnCommand() method in
SOURCE\OO\CLASSES\DIALOG.PRG.

TEXT | TITLE <cTitle>  specifies the title/caption (most
controls) or initial contents (e.g. for an edit control) for
the control.  Where possible, this value will be used when the
dialog is being created, whereas INITIAL | ITEMS specifies a
value to be used for dynamic initialisation (usually during
WM_INITDIALOG).

INITIAL | ITEMS <xInit> specifies a value to initialise the
control once it exists.  For some controls this is effectively
the same as TEXT | TITLE, although carried out later.  For
other controls, initialisation can be performed that cannot be
done by TEXT | TITLE, either because the control needs to
exist or because the <xInit> value is not a string.  For
example, <xInit> might be an array of values, as with a
ListBox.

ACTION <a> specifies an optional code block (instead of a
COMMAND) to execute if this control sends messages to the
dialog.  For a non-OO app, the code block is passed the dialog
handle, the control handle, the notification code sent by the
control (e.g. one of the CBN_*, EN_*, LBN_*, SB_* values in
WINDOWS.CH), and the control's id.  For an OO app, the code
block is passed the owning dialog object, the control object
and the notification code sent by the control.

VALID <v> specifies an optional code block to be used for
validation.  This block can be used many times during the
lifetime of a dialog, so it is not a good idea to prompt the
user.  For a non-OO app, the code block is passed the dialog
handle, the control handle and the control's id.  For an OO
app, the code block is passed the owning dialog object and the
control object.

AT <x>, <y>  specify the starting co-ordinates in dialog
units.  There are typically several pixels per dialog unit,
but it depends on the font and screen resolution.  See the
MapDialogRect() and GetDialogBaseUnits() functions for more
information.

FROM <x>, <y>  TO <r>, <b> is the same as:
          AT <x>, <y>  SIZE <r> - <x>, <b> - <y>

SIZE <w>, <h>  specify the width and height in dialog units.
See the AT clause above for more information.

WIDTH <w>  HEIGHT <h> is the same as SIZE <w>, <h>.

STYLE <nStyle>  specifies the window style (using the WS_*
values defined in WINDOWS.CH).  The default depends on the
type of control, but is usually CTL_DEFSTYLE (WS_VISIBLE +
WS_CHILD), with WS_TABSTOP in some cases.  Forgetting WS_CHILD
for a control in a dialog usually causes the dialog function
to return an error: -1 for DialogBox(), 0 for CreateDialog().

IN [ DIALOG ] <oDlg> | <aDlg>  specifies the dialog for the
control.  The default for non-OO is a variable named aDlg
(which therefore needs to exist and be meaningful).  For an OO
application the default is SELF.

Description
This manual entry is the generic documentation for all the
specific versions of this command.  It exists to describe the
clauses generally available for use with all the @ ID ...
commands.

The individual commands can be used in either a non-OO
application (by defining NO_C4WCLASS) or an OO application.
Some of the clauses depend on which kind of application is
being created - refer to COMMANDS.CH for details.  A number of
clauses may be ignored, to make it easier to convert from non-
OO to OO.

3-D effects will be applied if the 3-D control DLL (CTL3D.DLL)
is aware of the control type and is being used by your
application.  The command CREATE APPLICATION uses the DLL by
default, as do the WApp and WMDIApp classes.  If you don't
want the 3-D effects, you can specify NO 3D or set the :Ctl3D
property to false:
     oMyApp:Ctl3D := .F. // turn off 3-D

Borland custom controls can be used if you specified the BWCC
or BORLAND clause with CREATE APPLICATION or if you set your
application's :BWCC property to true:
     oMyApp:BWCC := .T.

Example
// For a resource dialog (see SOURCE\OO\USERSRES\USERSRES.PRG):
@ Id IDD_PHONE    Obj ::oPhone    Get ::cPhone
@ Id IDD_NEXT     PushButton  Next

// Resource (see SOURCE\OO\DBFGEN.PRG):
@ Id IDD_LEN  Obj ::oLen  Get ::cLen  Picture "999"  Valid val(::cLen) != 0
@ Id IDD_DEC  Obj ::oDec  Get ::cDec  Picture "9"

// Resource (see SOURCE\OO\VBXGEN.PRG):
@ Id IDD_VBXNAME  Obj ::oVBXName  Edit
@ Id IDD_SOURCE   Obj ::oSource   MultiLine Edit

// For a dynamic dialog (see SOURCE\OO\USERS\USERSCMD.PRG):
@ ID IDD_TPHONE  SAY  "P&hone:"                   AT 7,76   SIZE 50,8
@ Id IDD_PHONE   Obj ::oPhone  Get ::cPhone       AT 7,85   SIZE 115,13
@ ID IDD_NEXT    BUTTON Next   TITLE "&Next"      AT 132,61 SIZE 37,12

// Dynamic (see SOURCE\OO\CMD\COMBO.PRG):
@ ID 12 ComboBox  OBJ oCB2  ITEMS  a2  AT 20,70  SIZE 70,50 ;
    STYLE CBS_DROPDOWNLIST + WS_VSCROLL + CTLSTYLE          ;
    ACTION oText:Text := oCB2:CurItem  IN oDlg