dialog_programming.hlp

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

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 rarely are the extra capabilities needed
when specifying i-actions.


{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 should be
depends on how the user fills in the dialog box.

{pstd}
You, the dialog-box programmer, construct that 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}, and {hi:CANCEL} 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 first outputting the word
{hi:regress} and to follow that by the {varlist} the user specified in
the varlist field of the first dialog and to follow that by {opt if} {it:exp},
getting the expression from what the user filled in an edit field of the
second dialog, but do that only if the user filled in an expression.
Otherwise, the program would omit the {opt if} {it:exp} in its entirety and
then follow that by . . . .

{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.  Worry first about coding how the dialogs look, and worry second
about how to translate what the user specifies into the u-action.

{pstd}
Nevertheless, on the various commands that specify how dialogs look, there is
an option you can specify that will make writing the u-action program easier.
The communication option {opt option()}, so called because it 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}
and doing that, when you got to writing your dialog-box {hi:PROGRAM}, you
would find it easier to associate the {opt robust} option in the command
you are constructing with whether this box was checked.  Communication options
never alter how a control looks or works, they just make extra information
available to the {hi:PROGRAM} that makes 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; it is just that you code them differently.  In addition, in
the vast majority of dialog boxes, you never do this.

{pstd}
Nevertheless, if you were writing a dialog box to edit a Stata graph, you
might very well construct your dialog box so that it contained no u-actions
and only i-actions!  Some of those i-actions might invoke Stata commands and
would more resemble u-actions than i-actions, but they would nevertheless
still be i-actions because, syntactically, you would specify them that way.

{pstd}
As you already know, i-actions can invoke {hi:PROGRAM}s, and {hi:PROGRAM}s
serve two purposes:  the coding of i-actions and the 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}
Now that you know that i-actions and u-actions can be programmed to be
virtually indistinguishable, our advice to you is not to do that, 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, you will let many errors be handled in 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 up, and the user can easily fix them.  Errors come in two forms:
outright errors and consistency errors.  An example of an outright error would
be typing a number in an edit field that is supposed to contain a variable
name.  An example of 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 (the disabling
or even hiding of 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 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 to later 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()}, and 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:]}}


{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}
or {hi:VERSION 9.0} or {hi:VERSION 9.00}.  It makes no difference; all
three mean the same thing.

{pstd}
{hi:VERSION} must appear first in the {cmd:.dlg} file (it may be preceded by
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 continues 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:.dlg} 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 how {it:name} is defined{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 at 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} sets the position {it:x} and {it:y} for the dialog box relative
to Stata's main window and defines the overall size {it:xsize} and {it:ysize}
of the dialog box.


{title:Remarks}
 
{pstd}
The position {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.

{pstd}
{it:xsize} and {it:ysize} may not be specified as {cmd:.} because they specify
the overall size of the dialog box.  One discovers the size by
experimentation.  If you specify a size that is too small, some elements will
flow off the dialog box.  If you specify a size that is too large, there 
will be large amounts of white space on the right and bottom of the dialog
box.  Good initial guesses for {it:xsize} and {it:ysize} are 400 and 300.

{pstd}
{hi:POSITION} may be specified anyplace in the dialog code outside of
{hi:BEGIN} . . . {hi:END} blocks.  It does not matter where it is specified
because the entire {cmd:.dlg} file is processed before the dialog box is
displayed.


{marker remarks3.5}
{title:3.5 LIST}

{title:Syntax}

       {cmd:LIST} {it:newlistname}
           {cmd:BEGIN}
               {it:item}
               {it:item}
               . . . 
           {cmd:END}


{title:Description}

{pstd}
{hi:LIST} creates a named list for use in populating list and combo boxes.


{title:Example}