packaging/win32/MessageBox.txt

   1 Customisable MessageBox Plug-In (v0.98 beta 3)\r
   2 \r
   3 [  Archive Page: http://nsis.sourceforge.net/archive/???  ]\r
   4 \r
   5 --------------\r
   6 \r
   7 The Customisable MessageBox plug-in allows you to use a MessageBox in your installer which can be altered to how you want it to be.  You can control:\r
   8         *  the number of buttons shown\r
   9         *  the text each button shows\r
  10         *  a standard or customisable icon ( flexible so you can use the installer or other files )\r
  11         *  a fully working 'forth' button!\r
  12 \r
  13 The plug-in uses a few tricks to allow for the messagebox functionality to be altered so that the button text can finally be altered making [ Yes | Yes to All | No | No to All ] ( and anything else you care for ) possible.\r
  14 \r
  15 Also with the changes made it is now possible to have a functional 'forth' button - yes you read correctly!  When using the function just pass in four button texts and you will see the forth button - simple really :o)\r
  16 \r
  17 There is only the one function to show the messagebox so enjoy.\r
  18 \r
  19 [ As of v0.98 beta the parameters of calling the function have changed, check out usage for the revised options - thanks to n0On3 for the suggestions. ]\r
  20 \r
  21 \r
  22 Usage\r
  23 -----\r
  24 \r
  25 messagebox::show  styles  caption  ( module_name, icon_id )  text   but1  [ but2  but3  but4 ]\r
  26 \r
  27 styles - messagebox styles ( supports most of the windows messagebox styles )\r
  28 \r
  29 caption - the text to be used for the dialog title ( or the installer title if not specified )\r
  30 \r
  31 module_name - sets the name of the file ( usually a dll or exe file ) that contains the custom icon to be used - if 0 is passed then the installer will be used\r
  32 \r
  33 icon_id - the id of the icon group to be used for the custom icon\r
  34 \r
  35 text - the text to be shown by the messagebox\r
  36 \r
  37 but1 - specified text or name id to use ie IDYES, IDNO, etc ( there must always be at least one button )\r
  38 \r
  39 but2, but3, but4 - optional buttons which follow the same way as for but1\r
  40 \r
  41 \r
  42 When passing in options, you should use a "" pair for options you pass in to ensure the strings are correctly read.  It is not necessary to do so for the predefined button texts\r
  43 e.g. "IDCANCEL" is the same as IDCANCEL.\r
  44 \r
  45 See Example.nsi for an example ;o)  ( bit hacked at the moment due to testing but shows most things )\r
  46 \r
  47 \r
  48 Return Values\r
  49 -----\r
  50 \r
  51 To get the return value use Pop $0 immediately after the function has been used incase other functions alter the value.\r
  52 \r
  53 If there were no problems then the function will return the number of the button pressed working from the left being 'button 1'.\r
  54 i.e.\r
  55         if you have [ yes | no | abort ] and 'no' is selected then the return value will be '2'\r
  56 \r
  57 If an error happens then the messagebox will return 0.\r
  58 \r
  59 If there are no buttons passed then the function will return '-1'.\r
  60 \r
  61 \r
  62 Some More Info\r
  63 ----------------\r
  64 \r
  65 If you pass an empty string for the caption ( "" ) then the installer title text will be used instead (stripping back the current section name as NSIS messageboxes do).\r
  66 If the installer is run silently then the title will be blank if setting the caption option to "" ( as NSIS messageboxes do ).  This is because when the installer is silent it does not have a visible window and so will not have a window title ( had not taken this into account initially, oops - fixed from v0.98 beta 3 ).\r
  67 \r
  68 When you want to use a custom icon, setting module to '0' will look for the icon in the installer otherwise it will search the file specified.\r
  69 e.g.\r
  70         "0,103" will load the installer icon ( well in testing it does :o)  )\r
  71         "shell32.dll,24" will load the help file icon from the shell32.dll ( as long as the file exists! )\r
  72 \r
  73 If the module passed is not valid then the usericon style will not be used ( you may receive a windows message informing of this ).\r
  74 \r
  75 If the icon is not valid then the messagebox will just show a blank area where the icon would be displayed assuming that the value of module is valid.\r
  76 \r
  77 If a usericon is specified then if there are any of the messagebox icon styles passed in, these will be ignored.  This allows an icon to appear otherwise internal style conflicts will prevent any icon being shown.\r
  78 \r
  79 If you want to display the standard button texts then pass the following strings in for the necessary button:\r
  80 \r
  81         IDOK            -       Ok\r
  82         IDCANCEL        -       Cancel\r
  83         IDABORT -       Abort\r
  84         IDRETRY -       Retry\r
  85         IDIGNORE        -       Ignore\r
  86         IDYES           -       Yes\r
  87         IDNO            -       No\r
  88         IDHELP          -       Help / 4th button\r
  89         IDTRYAGAIN      -       Try Again\r
  90         IDCONTINUE      -       Continue\r
  91 \r
  92 When the function is processing the passed button texts to use, if a duplicate of the predefined texts (above) happen then the only the first instance will be allowed\r
  93 e.g.\r
  94         IDYES "ah go on if you dare" IDYES      ->      [  YES  |  ah go on if you dare  ]\r
  95 \r
  96 Each button will be resized if needed to allow the text to fit correctly in the button without being clipped.  If the text is still too long for the messagebox width ( limited to 80% of the screen width ) then buttons will be resized and clipping of the button text may happen again ( this will be fixed in v1.0 ).\r
  97 \r
  98 \r
  99 Final Notes\r
 100 -------\r
 101 \r
 102 I have no idea how the code will work with international text (since i just use plain text in the code) so if you try it in a multilanguage setup then let me know how it reacts or if there are any issues with the function's display.\r
 103 \r
 104 The predefined button texts are hard coded and cannot be altered.  To alter the default texts involves passing in the language button text as a custom button text.\r
 105 \r
 106 The button resizing code is not complete at the moment ( as can be clearly seen from the first messagebox ) when it detects that the width of the messagebox is at the 80% screen width.  Issues are that the buttons are not correctly resized to ensure that they appear correctly ( as is the case with the second messagebox ).  This is more down to fiddling with the button widths after the initial processing but will be fixed soon :o)\r
 107 \r
 108 \r
 109 Credits\r
 110 -------\r
 111 \r
 112 Coded by Darren Owen, aka DrO (Sept 2003)\r
 113 \r
 114 n0On3 - Idea request and helpful feedback ( the simplified function use over previous versions :o) )\r
 115 \r
 116 A plugin from me to you :o)\r
 117 \r
 118 \r
 119 Version History\r
 120 -------\r
 121 \r
 122 v0.1\r
 123 * Initial release of the function\r
 124 * Basic support to show that the button text can be altered on the messagebox\r
 125 * Inital support for controlling the number of buttons shown\r
 126 \r
 127 v0.5\r
 128 * Setting of text of only the buttons wanted ( "/but? blah" )\r
 129 * Now if a string is not passed then the text will not be set (broken in the v0.1 release)\r
 130 * Altered a lot of internal workings to allow for more customising of the MessageBox\r
 131 * Better support for the number of buttons to show\r
 132 * The functional '4th' button - making use of the 'Help' button to act as a real button\r
 133 * Fixed a number of crash issues due to buffer sizes and a few other bugs, etc\r
 134 \r
 135 v0.8\r
 136 * A lot of changes made :o)\r
 137 * Improved internal handling so that now button text is set correctly either when the number of buttons is set or user styles are set so now "/but2 blah" will always set the second buttons text and not just a few cases as beforehand\r
 138 * Altered the order of the parameters from earlier versions to make some internals easier to do :o)\r
 139 * The 4th / Help button will now close the MessageBox in ALL cases - would not close correctly if there was not a 'cancel' button in earlier versions\r
 140 * Buffers are now allocated to the NSIS buffer sizes passed to the dll on use for better compatibility between dll and installer\r
 141 * When the button numbers are set, the function will map the returned value now to the button selected instead of the normal wndows defined return value\r
 142 * some other bits and bobs that i've forgotten on the way\r
 143 \r
 144 v0.9\r
 145 * Added in support for displaying custom icons on the messagebox ( along with standard icons which can be shown ) either in the installer or from other files\r
 146 * Altered the example script to show off some more bits of what it can do\r
 147 \r
 148 v0.95 beta\r
 149 * Added in support for resizing of buttons based on the text set into the button ( use the /trim before the text to be set )\r
 150 * Messagebox is now limited to approximately 80% of the screen size ( as the messagebox normally does )\r
 151 * The resizing of button texts will also update the width of the text width to ensure it keeps to the size of the messagebox\r
 152 * Support is not complete for /trim ( still need to update the graduating of the width increment )\r
 153 * When the 80% width is reached, currently buttons will disappear off the messagebox ( handling for a double height button will come to cope with this soon )\r
 154 * Altered the example script to show off some more bits of what it can do\r
 155 \r
 156 v0.98 beta\r
 157 * Removed the passing in of a hwnd parameter - is always owned by the installer\r
 158 * Altered the custom icon option to be a single parameter now in the form 'module,id' where module can be 0 to use the installer\r
 159 * All return values are now mapped to the button number pressed ie 1,2,etc\r
 160 * Now the number of buttons to show is based on the button string texts passed in to the function :o)\r
 161 * Altered the order of parameters to work in a top to bottom order with respect to the messagebox layout and to match closer to the NSIS setup\r
 162 [ a good suggestion from n0On3 - nice ]\r
 163 - now goes:     style  title  usericon  text  but1  [ but2  but3  but4 ]\r
 164 * Altered the button texts to be set in the order passed and will also convert the default ids too! eg IDYES -> "Yes", IDIGNORE -> "Ignore"\r
 165 * Fixed the graduating of the button trim feature to appear 'natural'\r
 166 [ adds approxiamately 3 character widths either side when the text won't fit fully in the button ]\r
 167 * Fixed a few bugs in the code introduced in the changes made\r
 168 * Support for MB_DEFBUTTON? is broken when a button has to be resized ( will fix this soon - already worked out how to but not why this happens )\r
 169 \r
 170 v0.98 beta 2\r
 171 * Fixed the MB_DEFBUTTON? issue ( needed to prevent the wm_active message being handled )\r
 172 * Verified the installer will show icons correctly if the installer is run silently ( no code changes were made )\r
 173 * Added in checking of the defined buttons to ensure that duplicates are not allowed (only the first occurrance is allowed)\r
 174 * Checked that all strings are verified for having data before being used\r
 175 * A few code tidy-ups introduced to the code\r
 176 * Typo fix in the example\r
 177 * Added in stripping out of the icon definitions if a user icon is specified (otherwise no icon will appear!)\r
 178 * Updated the readme file to reflect the changes made to the plug-in's functionality since v0.98 beta and to clarify things in better detail now ( i hope )\r
 179 * Added in a reference to the archive page for the plugin ( will upload majority of this file to the archive )\r
 180 * All internal buffers are now set to the buffer size passed into the plugin when it is called and altered how they are referenced\r
 181 * Fixed how the module string is cleared, should fix a potential crash issue i hope\r
 182 * Partially fixed the resizing of the text area when using long button strings to correctly limit out when the 80% limit is reached ( fine when now icon is used at the moment )\r
 183 * Added a silent installer option to the example script, just !define SILENT to get the silent version (should show that the function works fine either in a normal or silent installer)\r
 184 \r
 185 v0.98 beta 3\r
 186 * Fixed a crash when a silent installer is run ( pointed out by n0On3 ) - not checking the string length when getting the installer title if ""is the pased caption value, doh!