dialog_programming.hlp

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

corner:  {it:x} is how far to the right and {it:y} is how far down.

{pstd}
Sizes are similarly indicated by a pair of numbers, {it:xsize} and 
{it:ysize}.  They, too, are measured in pixels and indicate the size starting
at the top-left corner of the object.

{pstd}
Any command that needs a position or a size always takes all four
numbers{hline 2}position and size{hline 2}and you must specify all four.  In
addition to each element being allowed to be a number, some extra codes are
allowed.  A position or size element is defined as
 
{p2colset 9 17 17 0}{...}
{p2col :{it:#}}any unsigned integer number, such as 0, 1, 10, 200, . . .{p_end}

{p2col :{it:.}}(period) meaning the context-specific default value for
whatever is this position/size element.  {cmd:.} is allowed only with heights
of controls (heights are measured from the top down) and for the initial
position of a dialog box.{p_end}

{p2col :{cmd:@}}means the previous value for this position/size element.
If {cmd:@} is used for an {it:x} or a {it:y}, then the {it:x} or {it:y} from
the preceding command will be used.  If {cmd:@} is used for an {it:xsize} or
a {it:ysize}, then the previous {it:xsize} or {it:ysize} will be used.{p_end}

{p2col :{cmd:+}{it:#}}means a positive offset from the last value (meaning to
the right or down or bigger).  If {cmd:+10} is used for {it:x}, the result
will be 10 pixels to the right of the previous.  If {cmd:+10} were used for a
{it:ysize}, it would mean 10 pixels taller.{p_end}

{p2col :{cmd:-}{it:#}}means a negative offset from the last value (meaning to
the left or up or smaller).  If {cmd:-10} is used for {it:y}, the result will
be 10 pixels above the previous.  If {cmd:-10} were used for a {it:xsize}, it
would mean 10 pixels narrower.{p_end}

{p2col :{it:name}}means the value last recorded for {it:name} by the 
{hi:DEFINE} command.{p_end}
{p2colreset}{...}

{pstd}
The {cmd:DEFINE} command has the syntax 

        {bind:DEFINE {it:name} { {cmd:.}|{it:#}|{cmd:+}{it:#}|{cmd:-}{it:#}|{cmd:@x}|{cmd:@y}|{opt @xs:ize}|{opt @ys:ize} }}

{pstd}
and may appear anywhere in your dialog code, even inside the 
{hi:BEGIN}/{hi:END} of {hi:DIALOG}.  Anywhere you need to specify a
position or size element, you can use a {it:name} defined by {hi:DEFINE}.

{pstd}
The first four possibilities for how {it:name} is defined have the obvious
meaning: {cmd:.} means default, {it:#} means number specified, {cmd:+}{it:#}
means positive offset, and {cmd:-}{it:#} means negative offset.  The other
four possibilities, {cmd:@x}, {cmd:@y}, {cmd:@xsize}, and {cmd:@ysize}, 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 was issued.


{marker remarks2.3}{...}
{title:2.3 Default values}

{pstd}
Another issue concerning the programming of input controls is loading them
with their initial, or default, values.  For instance, perhaps we want one
checkbox checked and another unchecked, and we want an edit field filled in
with "Default title".

{pstd}
The syntax of the {hi:CHECKBOX} command, which creates checkboxes, is 

        {bind:{hi:CHECKBOX} . . . {cmd:[,} . . .  {opt default(defnumval)} . . .{cmd:]}}

{pstd}
In checkboxes, the {opt default()} option specifies how the box is to be
filled in initially, and 1 corresponds to checked and 0 to unchecked.

{pstd}
The syntax of {hi:EDIT}, which creates edit fields, is 

        {bind:{cmd:EDIT} . . . {cmd:[,} . . . {opt default(defstrval)} . . .{cmd:]}}
 
{pstd}
In edit fields, {opt default()} specifies what the box is initially to 
contain.

{pstd}
Wherever {it:defnumval} appears in a syntax diagram, you may type 

{p2colset 5 34 36 2}{...}
{p2col :{it:defnumval}}meaning{p_end}
{p2line}
{p2col :{it:#}}meaning the number specified{p_end}
{p2col :{opt literal} {it:#}}same as {it:#}{p_end}
{p2col :{opt c(name)}}value of {opt c(name)}, see {helpb creturn}{p_end}
{p2col :{opt r(name)}}value of {opt r(name)}, see {helpb return}{p_end}
{p2col :{opt e(name)}}value of {opt e(name)}, see {helpb ereturn}{p_end}
{p2col :{opt s(name)}}value of {opt s(name)}, see {helpb return}{p_end}
{p2col :{cmd:global} {it:name}}value of global macro {cmd:$}{it:name}{p_end}
{p2line}
{p2colreset}{...}

{pstd}
Wherever {it:defstrval} appears in a syntax diagram, you may type 

{p2colset 5 34 36 2}{...}
{p2col :{it:defstrval}}meaning{p_end}
{p2line}
{p2col :{it:string}}meaning the string specified{p_end}
{p2col :{cmd:literal} {it:string}}same as {it:string}{p_end}
{p2col :{opt c(name)}}contents of {opt c(name)}, see {helpb creturn}{p_end}
{p2col :{opt r(name)}}contents of {opt r(name)}, see {helpb return}{p_end}
{p2col :{opt e(name)}}contents of {opt e(name)}, see {helpb ereturn}{p_end}
{p2col :{opt s(name)}}contents of {opt s(name)}, see {helpb return}{p_end}
{p2col :{cmd:char} {it:varname}[{it:charname}]}value of characteristic, see {helpb char}{p_end}
{p2col :{cmd:global} {it:name}}contents of global macro {cmd:$}{it:name}{p_end}
{p2line}
{p 4 6 2}Note: If {it:string} is enclosed in double quotes (simple or compound), the first set of such quotes are stripped.{p_end}
{p2colreset}{...}

{pstd}
List and combo boxes present the user with a list of items from which 
they may choose.  In the jargon, rather than specifying their initial 
or default values, the boxes are said to be populated.  The syntax for 
creating a list-box input control is 

        {bind:{cmd:LISTBOX} . . . {cmd:[,} . . . {opt contents(conspec)} . . .{cmd:]}}

{pstd}
Wherever a {it:conspec} appears in a syntax diagram, you may type 

{phang}
{cmd:list} {it:listname}{break}
populates the box with the specified list, which you create separately using
the {cmd:LIST} command.  {cmd:LIST} has the following syntax:

            {cmd:LIST}
                {cmd:BEGIN}
                    {it:item to appear}
                    {it:item to appear}
                    . . . 
                {cmd:END}

{phang}
{opt mat:rix}{break}
populates the box with the names of all matrices currently defined in Stata.

{phang}
{opt vec:tor}{break}
populates the box with the names of all 1{it:x}{it:k} and {it:k}{it:x}1
matrices currently defined in Stata.

{phang}
{cmd:row}{break}
populates the box with the names of all 1{it:x}{it:k} matrices currently
defined in Stata.

{phang}
{opt col:umn}{break}
populates the box with the names of all {it:k}{it:x}1 matrices currently
defined in Stata.

{phang}
{opt sq:uare}{break}
populates the box with the names of all {it:k}{it:x}{it:k} matrices currently
defined in Stata.

{phang}
{opt sca:lar}{break}
populates the box with the names of all scalars currently defined in Stata.

{phang}
{opt constr:aint}{break}
populates the box with the names of all constraints currently defined in
Stata.

{phang}
{opt est:imates}{break}
populates the box with the names of all saved estimates currently defined in
Stata.

{phang}
{cmd:char} {it:varname}{cmd:[}{it:charname}{cmd:]}{break}
populates the box with the elements of the characteristic 
{bind:{it:varname}{cmd:[}{it:charname}{cmd:]}}, parsed on spaces.

{phang}
{opt e(name)}{break}
populates the box with the elements of {opt e(name)}, parsed on spaces.

{phang}
{opt glo:bal}{break}
populates the box with the names of all global macros currently defined in
Stata.

{phang}
{opt valuelab:els}{break}
populates the box with the names of all values labels currently defined in
Stata.


{marker remarks2.4}{...}
{title:2.4 Memory (recollection)}

{pstd}
All the input control commands have a {opt default()} or {opt contents()}
option that specifies how the control is to be filled in, for example,

        {bind:{hi:CHECKBOX} . . . {cmd:[,} . . .  {opt default(defnumval)} . . .{cmd:]}}

{pstd}
In this command, if {it:defnumval} evaluates to 0, the checkbox starts by
being unchecked. Otherwise, it is checked.  If {opt default()} is not
specified, the box starts as being unchecked.

{pstd}
The emphasis is on starts:  dialogs remember how they were last filled in
during a session, so the next time the user invokes the dialog box that
contains this {hi:CHECKBOX} command, the {opt default()} option will be
ignored in favor of how the user last left it.  That is, the setting will 
be remembered unless you, the dialog-box programmer, specify the
input control's {opt nomemory} option:

        {bind:{hi:CHECKBOX} . . . {cmd:[,} . . . {opt default(defnumval)} {cmd:nomemory} . . .{cmd:]}}

{pstd}
{opt nomemory} specifies that the dialog-box manager not remember between
invocations how the control is filled in; it is always to reset it according
to the default, whether that default is explicitly specified or implied.

{pstd}
Whether or not you specify {opt nomemory}, explicit or implicit defaults are
also restored when the user presses the Reset helper button.

{pstd}
The contents of dialog boxes are only remembered during a session, not between
them.  Within a session, the {helpb discard} command causes Stata to forget
the contents of all dialog boxes.

{pstd}
The issue of initialization and memory is in fact more complicated than it
first appears.  Consider a list box.  A list box is populated, and might be
populated with the currently saved estimates.  If the dialog box containing
this list box is closed and reopened, the available estimates may have
changed.  Therefore, list boxes are always repopulated according to the
instructions given.  Even so, list boxes do remember the choice that was made.
If that choice is still among the possibilities, that choice will be the one
chosen unless {opt nomemory} is specified; otherwise, the choice goes back to
being the default{hline 2}the first choice in the list of alternatives.

{pstd}
The same issues arise with combo boxes, and that is why some controls have the
option {opt default()} and others {opt contents()}.  {opt default()} is used
once, and, after that, memory is substituted (unless {cmd:nomemory} is
specified).  {opt contents()} is always used{hline 2}{cmd:nomemory} or
not{hline 2}but the choice made is remembered (unless {cmd:nomemory} is
specified).


{marker remarks2.5}{...}
{title:2.5 I-actions and member functions}

{pstd}
I-actions{hline 2}intermediate actions{hline 2}refer to all actions taken
along the way to producing the u-action.  An i-action might disable or hide
controls when another control is checked or unchecked, although there are lots
of other possibilities.  I-actions are always optional.

{pstd}
I-actions are invoked by {opt on}{it:*}{cmd:()} options{hline 2}options
that begin with the letters "{opt on}".  For instance, the syntax for the
{hi:CHECKBOX} command{hline 2}the command for defining a checkbox
control{hline 2}is

        {bind:{hi:CHECKBOX} {it:controlname} . . . {cmd:[,} . . . {opt onclickon(iaction)} {opt onclickoff(iaction)} . . .{cmd:]}}

{pstd}
{opt onclickon()} is the i-action to be taken when the checkbox is checked,
and {opt onclickoff()} is the i-action for when the checkbox is unchecked.
You do not have to fill in the {opt onclickon()} and {opt onclickoff()}
options{hline 2}the checkbox will work fine taking no i-actions{hline 2}but
you may fill them in if you want, say, to disable or to enable other controls
when this control is checked.  For instance, you might code

        {bind:{cmd:CHECKBOX sw2} . . . {cmd:, onclickon(d2.sw3.show) onclickoff(d2.sw3.hide)} . . .}

{pstd}
{opt d2.sw3} is how you refer to the control named {opt sw3} in the dialog
{opt d2} (for instance, the control we just defined is named {opt sw2}).  
{opt hide} and {opt show} are called member functions.  {opt hide} is the
member function that hides a control and {opt show} is its inverse.  Controls
have other member functions as well; what member functions are available is
documented with the command that creates the specific control.

{pstd}
Many commands have {opt on}{it:*}{cmd:()} options that allow the specification
of i-actions.  When {it:iaction} appears in a syntax diagram, what is allowed
is

{phang}
{cmd:.} (period){break}
Do nothing; take no action.  This is the default if you do not specify the
{opt on}{it:*}{opt ()} option.

{phang}
{bind:{cmd:gaction} {cmd:{it:dialogname}.{it:controlname}.{it:memberfunction}} {cmd:[}{it:arguments}{cmd:]}}{break}
Execute the specified {it:memberfunction} on the specified control, where
{it:memberfunction} may be

{pmore}
{bind:{{cmd:hide}|{cmd:show}|{cmd:disable}|{cmd:enable}|{it:something_else} {cmd:[}{it:arguments}{cmd:]}}}

{pmore}
All controls provide the {it:memberfunctions} {opt hide}, {opt show}, 
{opt disable}, and {opt enable}, and some controls make other, special
{it:memberfunctions} available, too.

{pmore}
{opt hide} specifies that the control disappear from view (if it has not
already done so).  {opt show} specifies that it reappear (if it is not already
visible).

{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}
{it:arguments} are allowed in case the {it:memberfunction} needs them.  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
{it:string} contains a space.  When specifying an {it:iaction} inside the
parentheses of an option, it is easier to leave them off unless they are
required due to a space.  If you do specify them, 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}}};