dialog_programming.hlp

是一个经济学管理应用软件 很难找的 但是经济学学生又必须用到

{pmore}
{opt disable} specifies that the control be disabled (if is it not already).
{opt enable} specifies that it be enabled (if it is not already).

{pmore}
{opt setposition} specifies the new position and size of a control. 
{opt setposition} requires {it:arguments} in the form of
{bind:{it:x} {it:y} {it:xsize} {it:ysize}}. A dot can be used with any of the 
four {it:arguments} to mean the current value.

{pmore}
In some cases, {it:arguments} may require quotes.  For
instance, {hi:CHECKBOX} provides a special {it:memberfunction}

            {cmd:setlabel} {it:string}

{pmore}
which sets the text shown next to the checkbox, so you might specify
{bind:{cmd:onclickon}{cmd:(}{cmd:'"gaction main.robust.setlabel "Robust VCE""'}{cmd:)}}.
Anytime a {it:string} is required, you must place quotes around it if that
{it:string} contains a space.  When specifying an {it:iaction} inside the
parentheses of an option, it is easier to leave the quotes off unless they are
required.  If quotes are required, you must enclose the entire
contents of the option in compound double quotes as in the example above.

{phang}
{bind:{cmd:{it:dialogname}.{it:controlname}.{it:memberfunction} {cmd:[}{it:arguments}{cmd:]}}}{break}
Same as {opt gaction}; the {opt gaction} is optional.

{phang}
{bind:{cmd:action} {cmd:{it:memberfunction}} {cmd:[}{it:arguments}{cmd:]}}{break}
Same as {cmd:gaction}
{bind:{cmd:{it:currentdialog}.{it:currentcontrol}.{it:memberfunction}}};
executes the specified {it:memberfunction} on the current control.

{phang}
{cmd:view} {it:topic}{break}
Display {it:topic} in viewer; see {helpb view}.

{phang}
{cmd:script} {it:scriptname}{break}
Execute the specified script.  A script is a set of lines, each specifying an
{it:iaction}.  So, if you wanted to disable three things, {opt gaction} would
be insufficient.  You would instead define a script containing the three 
{opt gaction} lines.

{phang}
{cmd:program} {it:programname}{break}
Execute the specified dialog-box program.  Programs can do more than scripts
because they provide if-statement flow of control (among other things), but
they are more difficult to write, and typically the extra capabilities are
not needed when specifying i-actions.

{marker remarks2.5.7}{...}
{phang}
{cmd:create} {opt STRING|BOOLEAN} {it:propertyname}{break}
Creates a new instance of a dialog property. see {help dialogs##remarks6.:properties}
for usage.

{marker remarks2.6}{...}
{title:2.6 U-actions and communication options}

{pstd}
Remember that the ultimate goal of a dialog box is to construct a
u-action{hline 2}a Stata command to be executed.  What that command is
depends on how the user fills in the dialog box.

{pstd}
You construct the command by writing a dialog-box
program, also known as a {hi:PROGRAM}.  You arrange that the program be
invoked by specifying the {opt uaction()} option allowed with {hi:OK},
{hi:SUBMIT}, {hi:CANCEL} and {hi:COPY} u-action buttons.  For instance, the syntax of
{hi:OK} is

        {bind:{cmd:OK} . . . {cmd:[,} . . . {opt uaction(pgmname)} {opt target(target)} . . .{cmd:]}}

{pstd}
{it:pgmname} is the name of the dialog program you write, and {opt target()}
specifies how the command constructed by {it:pgmname} is to be executed.
In most cases, you will simply want Stata to execute the command, which 
could be coded {cmd:target(stata)}, but since that is the default, most 
programmers omit the {opt target()} option altogether.

{pstd}
The dialog-box program you write accesses the information the user has filled
in and outputs the Stata command to be executed.  Without going into details,
the program might say to construct the command by outputting the word
{hi:regress}, followed by the {varlist} the user specified in
the varlist field of the first dialog, and followed by {opt if} {it:exp},
getting the expression from what the user filled in an edit field of the
second dialog.

{pstd}
Dialogs and input controls are named, and in your dialog-box program, when you
want to refer to what a user has filled in, you refer to
{bind:{it:dialogname}{cmd:.}{it:inputcontrolname}}.  {it:dialogname} was
determined when you coded the {hi:DIALOG} command to create the dialog

            {cmd:DIALOG} {it:dialogname} . . .

{pstd}
and {it:inputcontrolname} was determined when you coded the input-control
command to create the input control, for instance

            {hi:CHECKBOX} {it:inputcontrolname} . . .

{pstd}
The details are discussed in section 5 {hi:PROGRAM}, but do not get lost in
the details.  Think first about coding how the dialogs look, and second
about how to translate what the user specifies into the u-action.

{pstd}
On the various commands that specify how dialogs look, you can specify
an option that will make writing the u-action program easier:
the communication option {opt option()}, which communicates
something about the control to the u-action program, is allowed with every
control.  For instance, on the {hi:CHECKBOX} command, you could code

            {bind:{hi:CHECKBOX} . . . {cmd:,} . . .  option(robust) . . . }

{pstd}
When you wrote your dialog-box {hi:PROGRAM}, you
would find it easier to associate the {opt robust} option in the command
you are constructing with this check box.  Communication options
never alter how a control looks or works: they just make extra information
available to the {hi:PROGRAM} and make writing the u-action routine
easier.

{pstd}
Do not worry much about communication options when writing your dialog.
Wait until you are writing the corresponding u-action program. Then
it will be obvious what communication options you should have specified, 
and you can go back and specify them.


{marker remarks2.7}{...}
{title:2.7 The distinction between i-actions and u-actions}

{pstd}
In this documentation, we distinguish between i-actions and u-actions, but, if
you read carefully, you will realize that the distinction is more syntactical
than real.  One way we have distinguished i-actions from u-actions is to note
that only u-actions can run Stata commands.  In fact, i-actions can also run
Stata commands; you just code them differently.  In
the vast majority of dialog boxes, you will not do this.

{pstd}
Nevertheless, if you were writing a dialog box to edit a Stata graph, you
might construct your dialog box so that it contained no u-actions
and only i-actions!  Some of those i-actions might invoke Stata commands.

{pstd}
As you already know, i-actions can invoke {hi:PROGRAM}s, and {hi:PROGRAM}s
serve two purposes:  coding of i-actions and coding of u-actions.
{hi:PROGRAM}s themselves, however, have the ability to submit commands to
Stata, and therein lies the key.  I-actions can invoke {hi:PROGRAM}s, and
{hi:PROGRAM}s can invoke Stata commands.  How this is done is 
discussed in sections 5.1.3 and 5.5.

{pstd}
We recommend that you not program i-actions and u-actions that are 
virtually indistinguishable, except in
rare, special circumstances.  Users expect to fill in a dialog box and to be
given the opportunity to press {hi:OK} or {hi:Submit} before anything too
severe happens.


{marker remarks2.8}{...}
{title:2.8 Error and consistency checking}

{pstd}
In filling in the dialogs you construct, the user might make errors.  One
alternative is simply to ignore that possibility and let Stata complain when
it executes the u-action command you construct.  Even in well-written dialog
boxes, most errors should be handled this way because discovering
all the problems would require rewriting the entire logic of the Stata
command.

{pstd}
Nevertheless, you will want to catch easy-to-detect errors while the dialog is
still open, and the user can easily fix them.  Errors come in two forms:
An outright error would be typing a number in an edit field that is supposed
to contain a variable name.  A consistency error would be checking two checkboxes
that are, logically speaking, mutually exclusive.

{pstd}
Most consistency errors you will want to handle at the dialog level, either by
design (if two checkboxes are mutually exclusive, perhaps the information
should be collected as radio buttons) or by i-actions (disabling
or even hiding some fields depending on what has been filled in).
The latter was discussed in section 2.5.

{pstd}
Outright errors can be detected and handled in dialog-box programs and are
usually detected and handled in the u-action program.  For instance, in your
dialog-box program, you can assert that 
{bind:{it:dialogname}{cmd:.} {it:inputcontrolname}} must be filled in and pop
up a custom error message if it is not.  Or the program code can be written so that
an automatically generated error message is presented.  You will find that all
input-control commands have an {opt error()} option; for example

            {bind:{cmd:VARLIST} . . . {cmd:[,} . . . {opt error(string)} . . .{cmd:]}}

{pstd}
The {opt error()} string provides the text to describe the control when the 
dialog-box manager presents an error.  For instance, if we specified

            {bind:{cmd:VARLIST} . . . {cmd:[,} . . . {opt error(dependent variable)} . . .{cmd:]}}

{pstd}
the dialog-box manager might use that information later to construct the error
message "dependent variable must be specified".

{pstd}
If you do not specify the {opt error()} option, the dialog-box manager will
use what was specified in the {opt label()}; otherwise, {cmd:""} is used.
The {opt label()} option specifies the text that usually appears near the
control describing it to the user, but {opt label()} will do double duty so
that you only need to specify {opt error()} when the two strings need to
differ.


{marker remarks3}{...}
{title:3. Commands}


{marker remarks3.1}{...}
{title:3.1 VERSION}

{title:Syntax}

{p 8 15 2}
{bind:{cmd:VERSION} {it:#}{cmd:[.}{it:##}{cmd:]} {cmd:[}{it:valid operating systems}{cmd:]}}


{title:Description}

{pstd}
{hi:VERSION} specifies how the commands that follow are to be interpreted.


{title:Remarks}

{pstd}
{hi:VERSION} must appear first in the {cmd:.dlg} file (it may be preceded by
comments).  In the current version of Stata, it should read {hi:VERSION 9},
{hi:VERSION 9.0}, or {hi:VERSION 9.00}.  It makes no difference; all
three mean the same thing.

{pstd}
Optionally {hi:VERSION} can specify one or more valid operating systems. 
Accepted values are WINDOWS, MACINTOSH, and UNIX. If none of these are
specified, all are assumed. 

{pstd}
Including {hi:VERSION} at the top is of vital importance.  Stata is under
continual development, so syntax and features can change.  Including
{hi:VERSION} is how you ensure that your dialog box will continue to work
as you intended.


{marker remarks3.2}{...}
{title:3.2 INCLUDE}

{title:Syntax}

{p 8 15 2}
{bind:{cmd:INCLUDE} {it:includefilename}}

{pstd}
where {it:includefilename} refers to {it:includefilename}{cmd:.idlg} and
must be specified without the suffix and without a path.


{title:Description}

{pstd}
{hi:INCLUDE} reads and processes the lines from {it:includefilename}{cmd:.idlg}
just as if they were part of the current file being read.  
{hi:INCLUDE} may appear in both {cmd:.dlg} and {cmd:.idlg} files.


{title:Remarks}

{pstd}
The name of the file is specified without a file suffix and without a path.
{cmd:.idlg} files are searched for along the ado-path, as are {cmd:.dlg}
files.

{pstd}
{hi:INCLUDE} may appear anywhere in the dialog code and may appear in both
{cmd:.dlg} and {cmd:.idlg} files; include files may {hi:INCLUDE} other
include files.  Files may contain multiple {hi:INCLUDE}s.  The maximum
nesting depth is 10.


{marker remarks3.3}{...}
{title:3.3 DEFINE}

{title:Syntax}

{p 8 14 2}
{cmd:DEFINE} {it:name}
{{cmd:.}|{it:#}|{cmd:+}{it:#}|{cmd:-}{it:#}|{cmd:@x}|{cmd:@y}|{opt @xs:ize}|{cmd:,}{opt @ys:ize}}


{title:Description}

{pstd}
{hi:DEFINE} creates {it:name}, which may be used in other commands wherever a
position or size element is required.


{title:Remarks}

{pstd}
The first four possibilities for defining {it:name}{hline 2}{cmd:.},
{it:#}, {cmd:+}{it:#}, and {cmd:-}{it:#}{hline 2}specify default, number
specified, positive offset, and negative offset.

{pstd}
The other four possibilities{hline 2}{opt @x}, {opt @y}, {opt @xsize}, and
{opt @ysize}{hline 2}refer to the previous {it:x}, {it:y}, {it:xsize}, and
{it:ysize} values, with previous meaning previous to the time the {cmd:DEFINE}
command is issued, not at the time {it:name} is used.


{marker remarks3.4}{...}
{title:3.4 POSITION}

{title:Syntax}

{p 8 16 2}
{bind:{cmd:POSITION} {it:x} {it:y} {it:xsize} {it:ysize}}


{title:Description}

{pstd}
{hi:POSITION} is used to set the location and size of the dialog box. 
{it:x} and {it:y} refer to the upper-left-hand corner of
the dialog box. {it:xsize} and {it:ysize} refer to the 
width and height of the dialog box.


{title:Remarks}
 
{pstd}
The positions {it:x} and {it:y} may each be specified as {cmd:.}, and Stata
will determine where the dialog box will be displayed; this is recommended.