dialog_programming.hlp

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

{smcl}
{* *! version 1.0.0  22jun2005}{...}
{cmd:help dialog programming}
{hline}

    {hi:[P] dialog programming} {hline 2} Dialog programming


{title:Description}

{pstd}
Dialog-box programs{hline 2}also called dialog resource files{hline 2}allow
you to define the appearance of a dialog box, specify how its controls work
when the user fills them in (such as hiding or disabling specific controls), 
and specify the ultimate action to be taken (such as running a Stata command)
when the user presses {hi:OK} or {hi:Submit}.


{title:Remarks}

{pstd}
Remarks are presented under the headings

        {hi:{help dialogs##intro:1. Introduction}}

        {hi:{help dialogs##remarks2:2. Concepts}}
        {hi:{help dialogs##remarks2.1:2.1 Organization of the .dlg file}}
        {hi:{help dialogs##remarks2.2:2.2 Position, sizes, and the DEFINE command}}
        {hi:{help dialogs##remarks2.3:2.3 Default values}}
        {hi:{help dialogs##remarks2.4:2.4 Memory (recollection)}}
        {hi:{help dialogs##remarks2.5:2.5 I-actions and member functions}}
        {hi:{help dialogs##remarks2.6:2.6 U-actions and communication options}}
        {hi:{help dialogs##remarks2.7:2.7 The distinction between i-actions and u-actions}}
        {hi:{help dialogs##remarks2.8:2.8 Error and consistency checking}}

        {hi:{help dialogs##remarks3:3. Commands}}
        {hi:{help dialogs##remarks3.1:3.1 VERSION}}
        {hi:{help dialogs##remarks3.2:3.2 INCLUDE}}
        {hi:{help dialogs##remarks3.3:3.3 DEFINE}}
        {hi:{help dialogs##remarks3.4:3.4 POSITION}}
        {hi:{help dialogs##remarks3.5:3.5 LIST}}
        {hi:{help dialogs##remarks3.6:3.6 DIALOG}}
        {hi:{help dialogs##remarks3.6.1:3.6.1 CHECKBOX on/off input control}}
        {hi:{help dialogs##remarks3.6.2:3.6.2 RADIO on/off input control}}
        {hi:{help dialogs##remarks3.6.3:3.6.3 SPINNER numeric input control}}
        {hi:{help dialogs##remarks3.6.4:3.6.4 EDIT string input control}}
        {hi:{help dialogs##remarks3.6.5:3.6.5 VARLIST and VARNAME string input controls}}
        {hi:{help dialogs##remarks3.6.6:3.6.6 FILE string input control}}
        {hi:{help dialogs##remarks3.6.7:3.6.7 LISTBOX list input control}}
        {hi:{help dialogs##remarks3.6.8:3.6.8 COMBOBOX list input control}}
        {hi:{help dialogs##remarks3.6.9:3.6.9 BUTTON special input control}}
        {hi:{help dialogs##remarks3.6.10:3.6.10 TEXT static control}}
        {hi:{help dialogs##remarks3.6.11:3.6.11 GROUPBOX static control}}
        {hi:{help dialogs##remarks3.6.12:3.6.12 FRAME static control}}
        {hi:{help dialogs##remarks3.6.13:3.6.13 COLOR input control}}
        {hi:{help dialogs##remarks3.6.14:3.6.14 EXP expression input control}}
        {hi:{help dialogs##remarks3.7:3.7 OK, SUBMIT, CANCEL, and COPY u-action buttons}}
        {hi:{help dialogs##remarks3.8:3.8 HELP and RESET helper buttons}}

        {hi:{help dialogs##remarks4:4. SCRIPT}}

        {hi:{help dialogs##remarks5:5. PROGRAM}}
        {hi:{help dialogs##remarks5.1:5.1 Concepts}}
        {hi:{help dialogs##remarks5.1.1:5.1.1 Vnames}}
        {hi:{help dialogs##remarks5.1.2:5.1.2 Enames}}
        {hi:{help dialogs##remarks5.1.3:5.1.3 rstrings: cmdstring and optstring}}
        {hi:{help dialogs##remarks5.1.4:5.1.4 Adding to an rstring}}
        {hi:{help dialogs##remarks5.2:5.2 Flow control commands}}
        {hi:{help dialogs##remarks5.2.1:5.2.1 if}}
        {hi:{help dialogs##remarks5.2.2:5.2.2 call}}
        {hi:{help dialogs##remarks5.2.3:5.2.3 exit}}
        {hi:{help dialogs##remarks5.3:5.3 Error checking and presentation commands}}
        {hi:{help dialogs##remarks5.3.1:5.3.1 require}}
        {hi:{help dialogs##remarks5.3.2:5.3.2 stopbox}}
        {hi:{help dialogs##remarks5.4:5.4 Command-construction commands}}
        {hi:{help dialogs##remarks5.4.1:5.4.1 by}}
        {hi:{help dialogs##remarks5.4.2:5.4.2 bysort}}
        {hi:{help dialogs##remarks5.4.3:5.4.3 put}}
        {hi:{help dialogs##remarks5.4.4:5.4.4 varlist}}
        {hi:{help dialogs##remarks5.4.5:5.4.5 ifexp}}
        {hi:{help dialogs##remarks5.4.6:5.4.6 inrange}}
        {hi:{help dialogs##remarks5.4.7:5.4.7 weight}}
        {hi:{help dialogs##remarks5.4.8:5.4.8 beginoptions and endoptions}}
        {hi:{help dialogs##remarks5.4.8.1:5.4.8.1 option}}
        {hi:{help dialogs##remarks5.4.8.2:5.4.8.2 optionarg}}
        {hi:{help dialogs##remarks5.4.9:5.4.9 allowxi and xi}}
        {hi:{help dialogs##remarks5.5:5.5 Command-execution commands}}
        {hi:{help dialogs##remarks5.5.1:5.5.1 stata}}
        {hi:{help dialogs##remarks5.5.2:5.5.2 clear}}
        {hi:{help dialogs##remarks5.6:5.6 Special scripts and programs}}

        {hi:{help dialogs##remarks6.:6. Properties}}
        
        {hi:{help dialogs##remarks7.:7. Example}}

        {hi:{help dialogs##AppendixA:Appendix A:  Jargon}}
        {hi:{help dialogs##AppendixB:Appendix B:  Class definition of dialog boxes}}
        {hi:{help dialogs##AppendixC:Appendix C:  Interface guidelines for dialog boxes}}


{marker intro}{...}
{title:1. Introduction}

{pstd}
At a programming level, the purpose of a dialog box is to produce a Stata
command to be executed.  Along the way, it hopefully provides the
user with an intuitive and consistent experience{hline 2}that is your job as a
dialog-box programmer{hline 2}but the ultimate output will be

       {cmd:list mpg weight} or
       {cmd:regress mpg weight if foreign} or
       {cmd:append using myfile}

{pstd}
or whatever other Stata command is appropriate.  Dialog boxes are limited to
executing a single Stata command, but that does not limit what you can do with
them because that Stata command can be an ado-file.  (Actually
there is another way around the one-command limit, which we will discuss in
{hi:5.1.3 rstring: cmdstring and optstring}.)

{pstd}
This ultimate result is called the dialog box's u-action.

{pstd}
The u-action of the dialog box is determined by the code you write, called
dialog code, which you store in a {cmd:.dlg} file.  The name of the {cmd:.dlg}
file is important because it determines the name of the dialog box.  When a
user types

       {cmd:. db regress}

{pstd}
{cmd:regress.dlg} is executed.  Stata finds the file the same way it finds
ado-files{hline 2}by looking along the ado-path; see {helpb sysdir}.
{cmd:regress.dlg} runs regress commands because of the 
dialog code that appears inside the {cmd:regress.dlg} file.  {cmd:regress.dlg}
could just as well execute {cmd:probit} commands or even {cmd:merge} commands
if the code were written differently.

{pstd}
{cmd:.dlg} files describe

{p 8 11 2}
1. how the dialogs look;

{p 8 11 2}
2. how the input controls of the dialogs interact with each other; and

{p 8 11 2}
3. how the u-action is constructed from the user's input.

{pstd}
Items (1) and (2) determine how intuitive and consistent the user finds the
dialog.  Item (3) determines what the dialog box does.  Item (2) determines
whether some fields are disabled or hidden, so they cannot be mistakenly filled
in until the user clicks something, checks something, or fills in a certain
result.


{marker remarks2}{...}
{title:2. Concepts}

{pstd}
A dialog box is composed of many elements, called controls, including static
text, edit fields, and checkboxes.  Input controls are those that the user
fills in, such as checkboxes and text-entry fields.  Static controls are fixed
text and lines that appear on the dialog box but that the user cannot change.
See {hi:Appendix A} below for definitions of the various types of controls,
as well as other related jargon.

{pstd}
In the jargon we use, a dialog box is comprised of dialogs, and dialogs are
comprised of controls.  When a dialog box contains multiple dialogs, only one
dialog is shown at a time.  In this case, access to the dialogs is made
possible through small tabs.  Clicking on the tab associated with a dialog
makes that dialog active.

{pstd}
The dialog box may contain the helper buttons Help (shown as a small button
with a question mark on it) and Reset (shown as a small button with an {hi:R}
on it).  These buttons appear in the dialog box{hline 2}not the individual
dialogs{hline 2}so in a multiple-dialog dialog box, they appear regardless
of the dialog (tab) selected.

{pstd}
The Help helper button displays a help file associated with the dialog box.

{pstd}
The Reset helper button resets the dialog box to its initial state.  Each time
a user invokes a particular dialog box, it will remember the values last set
for its controls.  The reset button allows the user to restore the default
values for all controls in the dialog box.

{pstd}
The dialog box may also include the u-action buttons {hi:OK}, {hi:Submit}, 
{hi:Copy}, and {hi:Cancel}.  Like the helper buttons, u-action buttons appear 
in the dialog box{hline 2}not the individual dialogs{hline 2}so in a 
multiple-dialog dialog box, they appear regardless of the dialog (tab) selected.

{pstd}
The {hi:OK} u-action button constructs the u-action, sends it 
to Stata for execution, and closes the dialog box.

{pstd}
The {hi:Submit} u-action button constructs the u-action, sends it
to Stata for execution, and leaves the dialog box open.

{pstd}
The {hi:Copy} u-action button constructs the u-action, sends it
to the clipboard, and leaves the dialog box open.

{pstd}
The {hi:Cancel} u-action button closes the dialog box without
constructing the u-action.

{pstd}
A dialog box does not have to have all these u-action buttons, but it 
needs at least one.

{pstd}
Thus the nesting is 

	Dialog box, which contains
	   Dialog 1, which contains
	      input controls and static controls
 	   Dialog 2, which is optional and which, if defined, contains
	      input controls and static controls
	   [.  .  .]
           Helper buttons, which are optional and which, if defined, contain
             [Help button]
             [Reset button]
           U-action buttons, which contain
             [OK button]
             [Submit button]
             [Copy button]
             [Cancel button]

{pstd}
Said differently, 

{p 8 11 2}
1. a dialog box must have at least one dialog, must have one set of u-action
buttons, and may have helper buttons;

{p 8 11 2}
2. a dialog must have at least one control and may have many controls; and

{p 8 11 2}
3. the u-action buttons may include any of {hi:OK}, {hi:Submit}, {hi:Copy}, and
{hi:Cancel} and must include at least one of them.


{pstd}
Here is a simple {cmd:.dlg} file that will execute the {cmd:kappa} command, 
although it does not allow {cmd:if} {it:exp} and {cmd:in} {it:range}:

    {hline 10} BEGIN {hline 10} mykappa.dlg {hline 33}

    // ----------------- set version number and define size of box ---------
    VERSION 9
    POSITION . . 290 200

    // ------------------------------------------- define a dialog ---------
    DIALOG main, label("kappa - Interrater agreement") 
    BEGIN
            TEXT    tx_var 10  10 270 ., label("frequency variables:")
            VARLIST vl_var  @ +20   @ ., label("frequencies")
    END

    // -------------------- define the u-action and helper buttons ---------
    OK     ok1, label("OK")
    CANCEL can1, label("Cancel")
    SUBMIT sub1, label("Submit")
    COPY   copy1,
    HELP   hlp1, view("help kappa")
    RESET  res1

    // --------------------------- define how to assemble u-action ---------
    PROGRAM command
    BEGIN
            put "kappa " 
            varlist main.vl_var
    END
    {hline 10} END {hline 10} mykappa.dlg {hline 35}


{marker remarks2.1}{...}
{title:2.1 Organization of the .dlg file}

{pstd}
A {cmd:.dlg} file consists of seven parts, some of which are optional:


    {hline 10} BEGIN {hline 10} {it:dialogboxname}.dlg{hline 28}
    VERSION 9               {it:Part 1:  version number}
    POSITION . . .          {it:Part 2:  set size of dialog box}
    DEFINE . . .            {it:Part 3, optional:  common definitions}
    LIST . . . 
    DIALOG . . .            {it:Part 4: dialog definitions}
        BEGIN                   
            FILE . . .      {it:        . . . which contain input controls}
            BUTTON . . . 
            CHECKBOX . . .
            COMBOBOX . . .
            EDIT . . .
            LISTBOX . . .
            RADIO . . .
            SPINNER . . .
            VARLIST . . .
            VARNAME . . .
    
            FRAME . . .     {it:        . . . and static controls}
            GROUPBOX . . . 
            TEXT . . .
        END
            {it:repeat} {it:DIALOG}. . . {it:BEGIN}. . . {it:END} {it:as necessary}

    SCRIPT . . .            {it:Part 5, optional:  i-action definitions}
        BEGIN               {it:        . . . usually done as scripts}
            . . .
        END
    PROGRAM . . .           {it:        . . . but sometimes as programs}
        BEGIN
            . . .
        END
    
    OK . . .                {it:Part 6:  u-action and helper button definitions}
    CANCEL . . . 
    SUBMIT . . .
    HELP . . .
    RESET . . .
    
    PROGRAM command         {it:Part 7:  u-action definition}
        BEGIN
            . . .
        END
    {hline 10} END {hline 10} {it:dialogboxname}.dlg{hline 28}

{pstd}
The {hi:VERSION} statement must appear at the top; the other parts may appear
in any order.

{pstd}
{it:I-actions}, mentioned in {it:Part 5}, are intermediate actions, such
as hiding or showing, disabling or enabling a control, or opening the
Viewer to display something, etc., while leaving the dialog up and 
waiting for the user to fill in more or press a u-action button.


{marker remarks2.2}{...}
{title:2.2 Positions, sizes, and the DEFINE command}