message-box/custom in Dialogs

• (message-box/custom title message button1-label button2-label button3-label parent style close-result) -> 1, 2, 3, or close-result
   title : string
     message : string
     button1-label : string (up to 200 characters), bitmap% object, or #f
   button2-label : string (up to 200 characters), bitmap% object, or #f
   button3-label : string (up to 200 characters), bitmap% object, or #f
   parent = #f : frame% or dialog% object or #f
   style = '(no-default) : list of symbols in '(default=1 default=2 default=3 no-default disallow-close number-order caution stop)
   close-result = #f : value

  Displays a message to the user in a (modal) dialog, using parent as the parent window if it is specified. The dialog's title is title. The message string can be arbitrarily long, and can contain explicit linefeeds or carriage returns for breaking lines.

  The dialog contains up to three buttons for the user to click. The buttons have the labels button1-label, button2-label, and button3-label, where #f for a label indicates that the button should be hidden.

  If the user clicks the button labelled button1-label, a 1 is returned, and so on for 2 and 3. If the user closes the dialog some other way -- which is only allowed when style does not contain 'disallow-close -- then the result is the value of close-result. For example, the user can usually close a dialog by typing an Escape. Often, 2 is an appropriate value for close-result, especially when Button 2 is a ``Cancel'' button.

  If style does not include 'number-order, the order of the buttons is platform-specific, and labels should be assigned to the buttons based on their role:

  • Button 1 is the normal action, and it is usually the default button. For example, if the dialog has an ``OK'' button, it is this one. Under Windows and X, this button is leftmost; under Mac OS, it is rightmost. Use this button for dialogs that contain only one button.

  • Button 2 is next to Button 1, and it often plays the role of ``Cancel'' (even when the default action is to cancel, such as when confirming a file replacement).

  • Button 3 tends to be separated from the other two (under Mac OS, it is left-aligned in the dialog). Use this button only for three-button dialogs.

  Despite the above guidelines, any combination of visible buttons is allowed in the dialog.

  If style includes 'number-order, then the buttons are displayed in the dialog left-to-right with equal spacing between all buttons, though aligned within the dialog (centered or right-aligned) in a platform-specific manner. Use 'number-order sparingly.

  The style list must contain exactly one of 'default=1, 'default=2, 'default=3, and 'no-default to determine which button (if any) is the default. The default button is ``clicked'' when the user types Return. If 'default=n is supplied but button n has no label, then it is equivalent to 'no-default.

  In addition, style can contain 'caution to make the dialog use a caution icon instead of the application (or generic ``info'') icon. Alternately, it can contain 'stop to make the dialog use a stop icon. If style contains both 'caution and 'stop, then 'caution is ignored.

  The class that implements the dialog provides a get-message method that takes no arguments and returns the text of the message as a string. (The dialog is accessible through the get-top-level-windows function.)