dialog_programming.hlp

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

{smcl}
{* 07apr2005}{...}
{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, to specify how the controls of
the dialog box interact with how the user fills them in (such as the hiding or
disabling of specific areas), and to specify the ultimate action that is 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.7:3.7 OK, SUBMIT, and CANCEL 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##6.Example:6. 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 is to be hoped that it 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 is to 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 can be done
because that Stata command can be an ado-file that you also write.  (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.  The file is found in the same way as Stata
looks for ado-files{hline 2}by looking along the ado-path; see {helpb sysdir}.
The fact that {cmd:regress.dlg} happens to run regress commands is due to 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 are to look;

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

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

{pstd}
Items (1) and (2) determine how intuitive and consistent the user finds the
experience.  Item (3) determines what the dialog box does.  Item (2) refers to
how some fields are disabled or hidden and so 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}and 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}, and
{hi:Cancel}.  Like the helper buttons, u-action buttons appear in the dialog
box{hline 2}not the individual dialogs{hline 2}and so in a multiple-dialog
dialog box, they appear regardless of the dialog (tab) selected.

{pstd}
The {hi:OK} u-action button means to construct the u-action and send it off
to Stata for execution and, in addition, to close the dialog box.

{pstd}
The {hi:Submit} u-action button means to construct the u-action and send it
off to Stata for execution but to leave up the dialog box.

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

{pstd}
A dialog box does not have to have all these u-action buttons, but it will
need 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]
             [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}, 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} myprog.pkg {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")
    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.pkg {hline 35}


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

{pstd}
A {cmd:.dlg} file consists of seven parts, although some of them 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 still
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}

{pstd}
Part of specifying how a dialog is to appear is defining where things go 
and how big they are.

{pstd}
Positions are indicated by a pair of numbers, {it:x} and {it:y}.  They are
measured in pixels, and are interpreted as being measured from the top-left