MAKEMSI quickly and reliably creates MSI files in a non-programmatic way\Source CodeCommandsDialogEntry

---

The "DialogEntry" Command

This command should only be used between "Dialog" and "/Dialog commands and is used to defined an entry field (including its label).

This command supports simple text entry fields as well as more complex controls like list or combo boxes. The "Read Me Dialogs" tip shows you how to create an empty dialog and add some controls that the "DialogEntry" command doesn't support.

Most often you statically define list items but if you need to examine the environment at install time to determine the options then you should see the "Dynamically Update Dialog Controls" tip.

This command takes these parameters:

• Label (required)
  The question (or label text). If too long you may need to adjust the "DIALOGTEMPLATE_LABEL_COLUMN_WIDTH" macro.

• Property (required)
  This is the name of the property to contain the entry fields text. You can assign default values by creating this property with the desired default value.

  The value should be supplied in all upper case so that it becomes a public property which allows it to be specified on the MSIEXEC.EXE command line possibly during a silent (automated) install.

  If the property's value is sensitive (password etc) then please list it in the "MsiHiddenProperties" property to ensure its value isn't logged.

• ToolTip (optional)
  This parameter allows you to supply a tooltip which is displayed when the mouse is over the entry field.

• PASSWORD (optional)
  Setting this parameter to "Y" makes it a password entry field which causes the typed in value to be hidden with "*" characters.

• TRIM (optional)
  This is a basic transformation which ensures that there are no spaces at the start or end of the value. The value will not appear to change on the edit field but the property will be adjusted if required.

  The default for this parameter can be set via the DEFAULT_DIALOGENTRY_TRIM macro. The initial value is "Y".

• CASE (optional)
  This is a basic transformation which can be used to convert the value to lower or upper case. The value will not appear to change on the edit field but the property will be adjusted if required. Pass "" for no changes to be performed or "L" for conversion to lower case and "U" for upper case.

  If you also supply the "MatchRe" parameter then the value can also be "?" to indicate a case-insensitive match is desired.

  The default for this parameter can be set via the DEFAULT_DIALOGENTRY_CASE macro. The initial value is "".

• Blank (optional)
  A basic validation. Is the field allowed to be empty? At least for now spaces make a field non-empty...

  The default for this parameter can be set via the DEFAULT_DIALOGENTRY_BLANK macro. The initial value is "N" (blank not OK so validate the field).

• Max (optional)
  This specifies the max number of characters allowed for this entry field, Windows Installer will prevent any more being entered.

• PreSorted (optional)
  For list type controls, you either supply the sort order (pass "Y") or Windows Installer alphabetically sorts the items (pass "N").

  The default for this parameter can be set via the DEFAULT_DIALOGENTRY_PRESORTED macro. The initial value is "Y".

• SameLine (optional)
  This parameter defaults to "N". If "Y" supplied then this control will follow the previous one (on the same line).

• Width (optional)
  This is the width of the entry field in Installer Units and not characters!

• LabelWidth (optional)
  Unless you use the "SameLine" (or "X" and "Y") parameters you probably want all lines to have the same label width so that all controls left align. This parameter alows basic positioning of the control relative to its label. If this parameter is 0 then a label is not generated.

• X (optional)
  This provides a mechanism for control placement, this is where the label will be positioned.

• Y (optional)
  This provides a mechanism for control placement, this is where the label will be positioned.

• Integer (optional)
  A validation. If this parameter is supplied then the field is expected to contain an integer value.

  If the value is empty then any integer is OK, otherwise you should pass the minimum and maximum values in the format "min to max" (for example "1 to 9").

  Note that a blank value is considered to be OK as it could have been validated with the "blank" parameter.

• Control (optional)
  Indicates the type of control and should be one of the following values:

  • EF
    Normal Entry Field (default).

  • XB[:False|True]
    A checkbox. You can supply the values that the property should have for unchecked and checked states (in that order). If not supplied then by default "0" and "1" are used.

    Please use "XB:|1" for now as anything else will cause unchecked items to become checked if you use a "back" button to return to a dialog.

  • ME:EditMask
    A field of type "MaskedEdit" which can restrict the characters typed and is useful for phone numbers etc.

    The "EditMask" is documented in the Windows Installer documention (most is however misleading or wrong), however a short summary follows:

    Code	Meaning
    #	This character is a digit (other digit codes are "%".)
    ?	This character stands for an alpha-numeric character (other alpha-numeric codes are "^_'").
    =	This character causes a "split" to occur for example the text "##=###" creates two input fields the first 2 and the next 3 digits long (a "-" character is displayed between these). Note that a split will allow occur at non-code characters for example "##.###" will do the same as the previous code except that the "." will be the seperator.
    <	There should be at most one instance of this character but if it exists then there must be a following ">" character. Everything to the outside of the "<...>" block is a constant portion which is not displayed in the dialog.
    >	This must exist if the "<" character code was used.
    @	This character should not appear in a "visible" part of the template (see the "<" and ">" characters). It generates a randomised digit.

    Any other template characters which will appear as is in the property (and on the dialog).

    The most important fact is that each character marks a fixed position and so any digits or characters you don't enter will be replaced with spaces! So for example if you were using a mask to capture an IP address you'd have to strip all spaces from the result yourself!

  • CB
    Combo Box (user can also enter value). See the "PreSorted" parameter for how items are ordered.

    The actual values which provide the user choice are supplied by a 2 or 3 column "#data" structure, column meaning is:

    1. Value
       If the option is chosen then the property will contain this value.

    2. Visible Text
       This is the text which will display in the "pulldown" portion of the "ComboBox". When selected the "Value" will be visibly displayed (well tell Microsoft...).

    3. Order Number
       If this 3rd parameter is not supplied then the order is assigned by MAKEMSI. If the 3rd column is supplied then it should be a positive integer or '' (to allocate one following the previous one). Sorting occurs from lowest to highest numbers.

  • CL
    Same as "CB" except that the user may not enter their own values.

  • LB
    A List Box. See the "PreSorted" parameter for how items are ordered.

    The actual values which provide the user choice are supplied by a 2 or 3 column "#data" structure, column meaning is:

    1. Value
       If the option is chosen then the property will contain this value.

    2. Visible Text
       This is the text which will display in the "pulldown" portion of the "ComboBox". When selected the "Value" will be visibly displayed (well tell Microsoft...).

    3. Order Number
       If this 3rd parameter is not supplied then the order is assigned by MAKEMSI. If the 3rd column is supplied then it should be a positive integer or '' (to allocate one following the previous one). Sorting occurs from lowest to highest numbers.

  • LV
    A listview is like a listbox but also has graphic icons.

    Same as "LB" except that a 3rd mandatory parameter is a key into the "Binary" table. The optional "Order Number" is shifted to the 4th position.

    Due to the "No Graphics in ListView Control" bug only alphabetic sorting is supported. Other features that don't occur on ListBoxes are are an unnecessary "horizontal scrollbar" and that the selected item doesn't come into view.

  • RB
    Radio Buttons User chooses one.

    The actual values which provide the user choice are supplied by a 1 to 4 column "#data" structure, column meaning is:

    1. Value
       If the option is chosen then the property will contain this value.

       One of the values you supply should be used to initialize the property whose name you supplied this becomes the default value on entry to the dialog.

    2. Visible Text
       This is the text which will display next to the "button". If not supplied then the "Value" will be used as the text as well.

    3. Width / Next Line Indicator
       If not supplied or "" then any following radio button will be on the next dialog "line".

       If a non-blank value supplied then it should be an integer which indicates how wide the "visible text" will be (a bit of trial and error or experience will be required). Any following radio button will appear on the same "line" the specified number of "installer units" after this one.

    4. ToolTip
       If non-blank then this is a tooltip which should be displayed if the user places the mouse over the item.

  • Text
    This means we only want the label...

• MatchRe (optional)
  If this value is non-blank then it is a regular expression which should match the fields contents.

  By default the match is case sensitive, if you don't care about the case then use "?" on the "CASE" parameter.

  If your expression never matches then check a verbose log to ensure there is no message about a syntax error in your expression, it would also pay to test your expression in the "Regular Expression Tester" tool.

• ControlName (optional)
  This parameter allows you to provide an internal identifier for the control, if not provided a suitable name is generated for you. You should provide this value if you want to supplement the MAKEMSI dialog capabilities with your own direct table manipulations.

Example of how it might look

The following picture has my configured "look and feel" (titlebar's contents, graphic bar on top, the icon in it and the bottom line etc). The Dialog ID is in the titlebar by choice as I built the dialog in "development mode".

It may also not exactly match the sample code as I may not keep this picture in exact sync with the code (either due to lack of time or bad memory).

Examples

;--- Insert after which dialog? (I never have a "UserRegistrationDlg") ------
#ifdef REMOVED_LicenseAgreementDlg          ;;Only exists if the dialog has been removed...
       #define InsertAfter WelcomeDlg
#else
       #define InsertAfter LicenseAgreementDlg
#endif

;--- Actually create the dialog and insert into the UI ----------------------
<$Dialog "Test Dialog #1" INSERT="<$InsertAfter>" Dialog="MyFirstSettingsDialog">
    ;--- Two entry fields with tooltips (one a password field) --------------
    <$DialogEntry Property="ANSWER1" Label="&Name:"     ToolTip="Enter the users name (max 10 characters)"     Max=10 Width=200>
    <$DialogEntry Property="ANSWER2" Label="&Password:" ToolTip="Enter the users password (max 20 characters)" Max=20 Password=Y>
    <$PropertyList "MsiHiddenProperties" Value="ANSWER2">   ;;Should not be logged...

    ;--- Try a "MaskedEdit" type entry field --------------------------------
    <$DialogEntry Property="ANSWER3" Label="IP &Address:" Control=^ME:###.###.###.###^ ToolTip="IP address (4 bytes 0-255)">

    ;--- Try an entry field which is validated via a regular expression -----
    <$DialogEntry Property="ANSWER4" Label=^&Start with "ABC":^ BLANK="Y" MatchRe="^ABC.+$" CASE="?" ToolTip=^Min 4 characters starting with "ABC" (any case)!^>

    ;--- Entry field for an integer in the range 80-90 ----------------------
    <$DialogEntry Property="ANSWER5" Label="Want &Integer 80-90:" Max="2" Width=35 Integer="80 to 90">

    ;--- Add a combo box (user can choose existing or enter their own) ------
    #data 'ComboBox_ANSWER6' 2
        ;--- Define sounds and a test description shown in the pull down ----
        "woof woof"     "Dog"
        "quack quack"   "Duck"
        "bah bah"       "sheep"
        "moo moo"       "cow"
        "meeow meeow"   "cat"
    #data                       ;;Note that we dynamically add a couple of entries in the custom action below
   <$DialogEntry Property="ANSWER6" Label="Choose a sound:" Control="CB">

   ;--- Check Box -----------------------------------------------------------
   <$DialogEntry Property="ANSWER7" Label="Want more Money?:" Control="XB:False|True" ToolTip="A silly question...">

   ;--- A Radio Button ------------------------------------------------------
   #data 'RadioButton_ANSWER8'
         ;--- All buttons on same dialog line (not over 3) ------------------
         'Yes'   'I accept'               '50'  'Got heaps of money have you?'
         'No'    'No way in a fit!'       '75'  'Smart decision...'
         'Maybe' "Maybe, Oh I don't know" '130' 'Oh well not everyone has brains'
   #data
   <$DialogEntry Property="ANSWER8" Label="Buy car for $1,000,000:" Control="RB">
<$/Dialog>


;--- A second dialog --------------------------------------------------------
#define? TRYME_INCLUDES_LISTVIEW        Y       ;;Y/N - Only room for ONE ListBox or ListView!
<$Dialog "Test Dialog #2" INSERT="MyFirstSettingsDialog">
    ;--- A text only line ---------------------------------------------------
    <$DialogEntry Label="Want to remove Existing files?" Control="Text" LabelWidth="300">

    ;--- The radio button ---------------------------------------------------
    #data 'RadioButton_REMOVE_FILES'
           'Yes'   'Yes'  ''    ^Please note that your Data can't be recovered!^
           'No'    'No'   ''    ''
    #data
    <$DialogEntry Property="REMOVE_FILES" Label="" Control="RB" LabelWidth="0">

    ;--- Which control? -----------------------------------------------------
    #if ['<$TRYME_INCLUDES_LISTVIEW $$UPPER>' = 'N']
        ;--- A ListBox ----------------------------------------------------------
        #data 'ListBox_LIST_VALUE' 2
            ;--- Define sounds and a test description shown in the pull down ----
            "One"   "Choose Me #1"
            "Two"   "Choose Me #2"
            "Three" "Choose Me #3"
            "Four"  "Choose Me #4"
            "Five"  "Choose Me #5"
            "Six"   "Choose Me #6"
            "Seven" "Choose Me #7"
            "Eight" "Choose Me #8"
            "Nine"  "Choose Me #9"
        #data
        <$DialogEntry Label="Choose a listbox value:" Control="TEXT">                                     ;;Want label on its own line
        <$DialogEntry Property="LIST_VALUE" Control="LB" LabelWidth="0" Label="Choose a listbox value:">  ;;Re-specify label ONLY for any failed validation message (don't display it here)
    #else
        ;--- A ListView ---------------------------------------------------------
        <$Binary Key="SomeGraphic.ico" "TryMe.ICO">     ;;Obviously in a real application you'd use more than one graphic!
        #data 'ListView_LIST_VALUE' 3
            ;--- Define sounds and a test description shown in the pull down ----
            "One"   "Choose Me #1"     "SomeGraphic.ico"
            "Two"   "Choose Me #2"     "SomeGraphic.ico"
            "Three" "Choose Me #3"     "SomeGraphic.ico"
            "Four"  "Choose Me #4"     "SomeGraphic.ico"
            "Five"  "Choose Me #5"     "SomeGraphic.ico"
            "Six"   "Choose Me #6"     "SomeGraphic.ico"
            "Seven" "Choose Me #7"     "SomeGraphic.ico"
            "Eight" "Choose Me #8"     "SomeGraphic.ico"
            "Nine"  "Choose Me #9"     "SomeGraphic.ico"
        #data
        <$DialogEntry Label="Choose a listview value:" Control="TEXT">                                                 ;;Want label on its own line
        <$DialogEntry Property="LIST_VALUE" Control="LV" Width="120" LabelWidth="0" Label="Choose a listview value:">  ;;Re-specify label ONLY for any failed validation message (don't display it here)
    #endif
<$/Dialog>

See the "TryMeWithUserDialog.MM" sample to see a complete example with realistic supporting code.

Please email me any feedback, additional information or corrections. See this page online (look for updates) MAKEMSI© is (C)opyright Dennis Bareis 2003-2008 (All rights reserved). Saturday May 28 2022 at 3:11pm Visit MAKEMSI's Home Page