NAME

       AcknowledgeDialog,  BasicDialog,  ConfirmDialog,  GridDialog,  PrintDialog,  UChooser  - an assortment of
       useful dialog boxes

SYNOPSIS

       #include <Unidraw/dialogs.h>

DESCRIPTION

       BasicDialog  is  the  base  class  for  subclasses  that  implement  simple  but  common  dialog   boxes.
       AcknowledgeDialog  simply displays a one or two line message with a PushButton for dismissing the dialog.
       ConfirmDialog displays one or two lines of  descriptive  text  with  three  pushbuttons  marked  ``Yes,''
       ``No,''  and  ``Cancel'',  all  of which dismiss the dialog. ConfirmDialog also provides an interface for
       retrieving the button pushed.  GridDialog lets the user specify  the  resolution  of  a  cartesian  grid.
       PrintDialog  is  a FileChooser for specifying the name of a file or a printer.  Finally, UChooser extends
       the StringChooser protocol to provide additional useful features, including support for alphabetizing its
       StringBrowser's contents and for embellishing the dialog with descriptive text.

BASICDIALOG PUBLIC OPERATIONS

       void SetTitle(const char*)
       void SetSubtitle(const char*)
              BasicDialogs  can  display  one or two lines of descriptive text.  These functions change the text
              appearing in these lines.  The change appears immediately if the dialog is visible.

BASICDIALOG PROTECTED OPERATIONS

       BasicDialog(
           ButtonState*, const char* title = ``'',
           const char* subtitle = ``'', Alignment = Center
       )

       BasicDialog(
           const char*, ButtonState*, const char* title = ``'',
           const char* subtitle = ``'', Alignment = Center
       )
              Instantiate a BasicDialog, supplying an optional instance name, a button state, title and subtitle
              strings,  and the dialog's alignment, which is used by its Popup operation.  These operations will
              initialize two protected MarginFrame member variables, _title and _subtitle,  which  will  contain
              either  a  Message  instance  with  the specified string or a piece of glue if the string is null.
              These MarginFrames will be composed vertically at the top of the dialog,  and  no  vertical  space
              will be taken up by a null title or subtitle string.

       virtual void Forward(Event&)
       boolean IsAChild(Interactor*)
              These  functions are useful for rejecting spurious events while the dialog is visible, effectively
              locking out the rest of the application.  If Forward's event argument has x and y coordinates that
              fall  within  the dialog's canvas, then Forward calls Handle on the event's target.  Otherwise the
              BasicDialog's Handle is called.  IsAChild returns true if the given interactor is a child  of  the
              dialog.

ACKNOWLEDGEDIALOG PUBLIC OPERATIONS

       AcknowledgeDialog(const char* title, const char* subtitle)
              Construct an AcknowledgeDialog instance with the given title and subtitle.

       virtual void Acknowledge()
              Call  this  function  when the application should wait for the user to acknowledge the dialog.  It
              returns when the user has pressed and released the dialog's push button.  This function  does  not
              pop up the dialog.

CONFIRMDIALOG PUBLIC OPERATIONS

       ConfirmDialog(const char* title, const char* subtitle)
              Construct a ConfirmDialog instance with the given title and subtitle.

       virtual char Confirm()
              Call  this  function  when  the  application  should  wait for the user to confirm the dialog.  It
              returns 'y', 'n', or '^G' ('\007'), depending whether the  ``Yes,''  ``No,''  or  ``Cancel''  push
              button was pressed, respectively. This function does not pop up the dialog.

GRIDDIALOG PUBLIC OPERATIONS

       GridDialog()
              Construct  a  GridDialog  instance.  The GridDialog contains a MatchEditor instance for specifying
              the size of the grid's graduations in the x and y axes.  The user  can  specify  these  values  in
              pixels, points, centimeters, or inches by clicking on the appropriate radio button.

       virtual void GetValues(float& xincr, float& yincr)
              Return the user-specified values for the size of the grid's graduations, in pixel units.

       void SelectMessage()
              Highlight the values in the dialog's MatchEditor.

PRINTDIALOG PUBLIC OPERATIONS

       PrintDialog(boolean to_printer = true)
              Construct  a  PrintDialog  instance,  optionally specifying whether the dialog should prompt for a
              printer name or a file name.

       void ToPrinter(boolean)
       boolean ToPrinter()
              Specify and Return whether or not the string specified in the  PrintDialog  refers  to  a  printer
              name.

UCHOOSER PUBLIC OPERATIONS

       UChooser(
           const char* title, const char* subtitle,
           const char* acceptLabel, const char* sample
       )
              Construct  a UChooser instance.  The title and subtitle parameters specify the descriptive text at
              the top of the  dialog  box.   This  constructor  initializes  two  protected  MarginFrame  member
              variables  _title  and  _subtitle  that  are  analogous  to  the corresponding BasicDialog members
              described above.

       void Clear()
              Removes all strings from the UChooser's string browser.

       void Include(const char*)
       void Exclude(const char*)
              Include inserts a string into the string browser at a position defined by the UChooser's  Position
              function,  described  below.   Exclude  removes  the given string from the string browser.  If the
              string browser contains more than one copy of the string, then Exclude removes the  one  with  the
              smallest index.

       void SetTitle(const char*)
       void SetSubtitle(const char*)
              These  functions  change  the  text appearing in UChooser's title or subtitle.  The change appears
              immediately if the dialog is visible.

UCHOOSER PROTECTED OPERATIONS

       UChooser(ButtonState*, int rows, int cols, Alignment)
              Direct the UChooser to initialize  itself  with  a  string  browser  of  the  given  size  without
              initializing  the  MarginFrame members.  Subclasses that require a different look-and-feel can use
              this constructor to avoid creating MarginFrames or Messages they don't need.  The Init,  Interior,
              and  AddScroller  functions  (described  below) factor out different parts of the default look and
              feel, allowing subclasses to use parts of it.

       void Init(const char* title, const char* subtitle)
              Explicitly initialize the MarginFrame members to display the given title and/or subtitle strings.

       Interactor* Interior(const char* acceptLabel)
              Return an interactor that composes the UChooser's default look and feel.

       Interactor* AddScroller(Interactor*)
              Return a composition containing the given interactor with a  vertical  scroll  bar  and  adjusters
              along its right side, initializing them to scroll the interactor.  The Interior function uses this
              operation to provide the string browser's  scrolling interface.

       virtual int Position(const char*)
              Return an appropriate string browser index for  the  given  string.   By  default,  this  function
              returns  the  index  that  will  place  the string in alphabetical order among those in the string
              browser.

SEE ALSO

       Button(3I),   Dialog(3I),   Event(3I),   FileChooser(3I),   Frame(3I),   MatchEditor(3I),    Message(3I),
       StringBrowser(3I), StringChooser(3I), StringEditor(3I)