MessageBox.txt revision 218b26070a41a5d1b25911b027cc93ffcc1e7c34
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassCustomisable MessageBox Plug-In (v0.98 beta 3)
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass[ Archive Page: http://nsis.sourceforge.net/archive/??? ]
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass--------------
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassThe 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:
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * the number of buttons shown
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * the text each button shows
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * a standard or customisable icon ( flexible so you can use the installer or other files )
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * a fully working 'forth' button!
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassThe 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.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassAlso 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)
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassThere is only the one function to show the messagebox so enjoy.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass[ 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. ]
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glassmessagebox::show styles caption ( module_name, icon_id ) text but1 [ but2 but3 but4 ]
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glassstyles - messagebox styles ( supports most of the windows messagebox styles )
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glasscaption - the text to be used for the dialog title ( or the installer title if not specified )
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glassmodule_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
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glassicon_id - the id of the icon group to be used for the custom icon
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glasstext - the text to be shown by the messagebox
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glassbut1 - specified text or name id to use ie IDYES, IDNO, etc ( there must always be at least one button )
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glassbut2, but3, but4 - optional buttons which follow the same way as for but1
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassWhen 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
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glasse.g. "IDCANCEL" is the same as IDCANCEL.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassSee Example.nsi for an example ;o) ( bit hacked at the moment due to testing but shows most things )
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassReturn Values
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassTo get the return value use Pop $0 immediately after the function has been used incase other functions alter the value.
b329eb7b3f67e8e7635f0b1c88899119470a91edDav GlassIf there were no problems then the function will return the number of the button pressed working from the left being 'button 1'.
b329eb7b3f67e8e7635f0b1c88899119470a91edDav Glass if you have [ yes | no | abort ] and 'no' is selected then the return value will be '2'
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassIf an error happens then the messagebox will return 0.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassIf there are no buttons passed then the function will return '-1'.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassSome More Info
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass----------------
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassIf 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).
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassIf 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 ).
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassWhen 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.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass "0,103" will load the installer icon ( well in testing it does :o) )
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass "shell32.dll,24" will load the help file icon from the shell32.dll ( as long as the file exists! )
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassIf the module passed is not valid then the usericon style will not be used ( you may receive a windows message informing of this ).
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassIf 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.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassIf 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.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassIf you want to display the standard button texts then pass the following strings in for the necessary button:
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass IDCANCEL - Cancel
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass IDABORT - Abort
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass IDRETRY - Retry
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass IDIGNORE - Ignore
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass IDHELP - Help / 4th button
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass IDTRYAGAIN - Try Again
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass IDCONTINUE - Continue
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassWhen 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
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass IDYES "ah go on if you dare" IDYES -> [ YES | ah go on if you dare ]
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassEach 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 ).
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassI 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.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassThe 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.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassThe 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)
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassCoded by Darren Owen, aka DrO (Sept 2003)
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glassn0On3 - Idea request and helpful feedback ( the simplified function use over previous versions :o) )
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassA plugin from me to you :o)
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassVersion History
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass* Initial release of the function
d60f68a8534f619bb0a3e59eea03a84a2f69021dDav Glass* Basic support to show that the button text can be altered on the messagebox
* 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
* 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
* Buffers are now allocated to the NSIS buffer sizes passed to the dll on use for better compatibility between dll and installer
* 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
* 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
* Added in support for resizing of buttons based on the text set into the button ( use the /trim before the text to be set )
* Messagebox is now limited to approximately 80% of the screen size ( as the messagebox normally does )
* The resizing of button texts will also update the width of the text width to ensure it keeps to the size of the messagebox
* 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 )
* 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
* Now the number of buttons to show is based on the button string texts passed in to the function :o)
* 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
* Altered the button texts to be set in the order passed and will also convert the default ids too! eg IDYES -> "Yes", IDIGNORE -> "Ignore"
* 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 )
* Verified the installer will show icons correctly if the installer is run silently ( no code changes were made )
* Added in checking of the defined buttons to ensure that duplicates are not allowed (only the first occurrance is allowed)
* Added in stripping out of the icon definitions if a user icon is specified (otherwise no icon will appear!)
* 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 )
* Added in a reference to the archive page for the plugin ( will upload majority of this file to the archive )
* All internal buffers are now set to the buffer size passed into the plugin when it is called and altered how they are referenced
* 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 )