Note: This section of the documentation has been superceded by the more recent topic, Named Parameters in Subroutines.
-----------------------
*BETA* Compiler enhancement (edit 650): implement named XCALL parameters. Rather than simply listing all of the parameters in order, you can now declare symbolic names for the parameters of XCALLs and then specify them in the XCALL statement. For example:
xcall AUI, AUI_CONTROL, CTLOP_ADD, ctext="Hello World", ctype=MBF_STATIC, xyxy=5,10,5,30, fontscale=125
This is particularly handy with XCALLs that have many arguments.
To enable the use of named parameters for a specific XCALL, you must specify a ++DECLARE statement using the following syntax:
++DECLXCALL xcallname{+|,}pname{|alias}{=defval},pname{|alias}{=defval}...
Arguments with explicit =defval clauses will be assigned those default values if the argument is not specified and a later one is specified. Arguments without explicit defaults will be assigned implicit defaults of numeric 0, or, if the argument name ends in $, then literal "". The special default value @ is not really a default but an indicator that the parameter is relatively mandatory—i.e. if any later parameters are specified, then this parameter must be explicitly specified.
For example:
++DECLXCALL INFLD, row|rowcol,col,xmax|xmaxmin,xmin,type,entry=@,inxctl, &
parentid=1,opcode=2,exitcode=@,timer,cmdflg,defpt=-1,maxpt=-1, &
funmap=-1,setdef="",infclr,hlpidx="",maxchrs
The first parameter, "row|rowcol", illustrates the use of an alias. The idea here is that you could name both the row and col parameters separately, i.e. row=5,col=10, or you could save a little typing using rowcol=5,10. The parameter definition defpt=-1 indicates that if any parameters beyond defpt or specified (e.g. perhaps setdef), then defpt will default to -1.
Once declared this way, you can reference the named parameters in an XCALL statement. Note that you can start with one or more traditional (ordered) parameters, then switch to named ones. Any unnamed (ordered) parameters beyond a named parameter are just assigned to the next parameter position. For example, rowcol=5,10 assigns 5 to the parameter named rowcol (same as row), and then the 10 is assigned to the next parameter in order (col).
For example:
xcall INFLD, 5,10, xmaxmin=15,2, type="A|G||C", entry=ebuf, exitcode=exitcode, setdef=",one,two,three,,"
This would be interpreted by the compiler equivalently to:
xcall INFLD,5,10,15,2,"A|G||C",ebuf,0,1,2,exitcode,0,0,-1,-1,-1,setdef
Note that the inxctl parameter, which wasn't specified, defaults to numeric 0. Likewise for parentid and opcode except they have explicit defaults of 1 and 2, respectively. Timer and cmdflg have no defaults and thus default to literal 0. defpt, maxpt, funmap all default to explicit -1.
For XCALLs like AUI and MIAMEX that have many forms, with the form being determined by the first parameter, you can created declarations that combine the name and first parameter value by separating them with a "+" instead of a ",". For example:
++DECLXCALL AUI+AUI_CONTROL,opcode=CTLOP_ADD,ctlid,ctext=NUL_CTEXT$, &
cstate=MBST_ENABLE,ctype=MBF_STATIC+MBF_LFJUST,cmd=NUL_CMD$,
func=NUL_FUNC$,cstatus=NUL_CSTATUS,xyxy|srow,scol,erow,ecol, &
rgb|fgc=NUL_FGC,bgc=NUL_BGC,fontattr=NUL_FONTATTR, &
fontscale=NUL_FONTSCALE,fontface=NUL_FONTFACE$,tooltip$=NUL_TOOLTIP$, &
parentid=NUL_PARENTID,winclass=NUL_WINCLASS$,winstyle=NUL_WINSTYLE, &
winstylex=NUL_WINSTYLEX,ctype2=NUL_CTYPE2
++DECLXCALL AUI+AUI_WINDOW, opflag=SW_QUERY,ltrb|lft,top,rgt,btn, &
rowcol|row,col,tsts,bsts,cid,hg,vg,monitors,winsts
The above two declarations are both for XCALL AUI, but the "+" binds the AUI_CONTROL or AUI_WINDOW to the declaration name so that the two formats are distinct.
Usage example:
xcall AUI, AUI_CONTROL, "dlgTest", ctype=MBF_DIALOG, ctype2=MBF2_DLGNOCAP, xyxy=5,10,11,50, parentid="dlgMain"
xcall AUI, AUI_WINDOW, winsts=wstatus
WARNING: This functionality and syntax is likely to change somewhat before this is fully stabilized, so the feature should only be used for experimentation until further notice.
