interface/richtext/richtextsymboldlg.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        richtext/richtextsymboldlg.h
   3 // Purpose:     interface of wxSymbolPickerDialog
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxSymbolPickerDialog
  11     @headerfile richtextsymboldlg.h wx/richtext/richtextsymboldlg.h
  12
  13     wxSymbolPickerDialog presents the user with a choice of fonts and a grid
  14     of available characters. This modal dialog provides the application with
  15     a selected symbol and optional font selection.
  16
  17     Although this dialog is contained in the rich text library, the dialog
  18     is generic and can be used in other contexts.
  19
  20     To use the dialog, pass a default symbol specified as a string, an initial font
  21     name,
  22     and a current font name. The difference between the initial font and
  23     current font is that the initial font determines what the font control will be
  24     set to when the dialog shows - an empty string will show the selection @e
  25     normal text.
  26     The current font, on the other hand, is used by the dialog to determine what
  27     font
  28     to display the characters in, even when no initial font is selected.
  29     This allows the user (and application) to distinguish between inserting a
  30     symbol in the current font, and inserting it with a specified font.
  31
  32     When the dialog is dismissed, the application can get the selected symbol
  33     with GetSymbol and test whether a font was specified with UseNormalFont,
  34     fetching the specified font with GetFontName.
  35
  36     Here's a realistic example, inserting the supplied symbol into a
  37     rich text control in either the current font or specified font.
  38
  39     @code
  40     wxRichTextCtrl* ctrl = (wxRichTextCtrl*) FindWindow(ID_RICHTEXT_CTRL);
  41
  42         wxTextAttr attr;
  43         attr.SetFlags(wxTEXT_ATTR_FONT);
  44         ctrl-GetStyle(ctrl-GetInsertionPoint(), attr);
  45
  46         wxString currentFontName;
  47         if (attr.HasFont() && attr.GetFont().Ok())
  48             currentFontName = attr.GetFont().GetFaceName();
  49
  50         // Don't set the initial font in the dialog (so the user is choosing
  51         // 'normal text', i.e. the current font) but do tell the dialog
  52         // what 'normal text' is.
  53
  54         wxSymbolPickerDialog dlg(wxT("*"), wxEmptyString, currentFontName, this);
  55
  56         if (dlg.ShowModal() == wxID_OK)
  57         {
  58             if (dlg.HasSelection())
  59             {
  60                 long insertionPoint = ctrl-GetInsertionPoint();
  61
  62                 ctrl-WriteText(dlg.GetSymbol());
  63
  64                 if (!dlg.UseNormalFont())
  65                 {
  66                     wxFont font(attr.GetFont());
  67                     font.SetFaceName(dlg.GetFontName());
  68                     attr.SetFont(font);
  69                     ctrl-SetStyle(insertionPoint, insertionPoint+1, attr);
  70                 }
  71             }
  72         }
  73     @endcode
  74
  75     @library{wxrichtext}
  76     @category{cmndlg}
  77 */
  78 class wxSymbolPickerDialog : public wxDialog
  79 {
  80 public:
  81     //@{
  82     /**
  83         Constructors.
  84
  85         @param symbol
  86             The initial symbol to show. Specify a single character in a string, or an
  87         empty string.
  88         @param initialFont
  89             The initial font to be displayed in the font list. If empty, the item
  90         normal text will be selected.
  91         @param normalTextFont
  92             The font the dialog will use to display the symbols if the initial font is
  93         empty.
  94         @param parent
  95             The dialog's parent.
  96         @param id
  97             The dialog's identifier.
  98         @param title
  99             The dialog's caption.
 100         @param pos
 101             The dialog's position.
 102         @param size
 103             The dialog's size.
 104         @param style
 105             The dialog's window style.
 106     */
 107     wxSymbolPickerDialog(const wxString& symbol,
 108                          const wxString& initialFont,
 109                          const wxString& normalTextFont,
 110                          wxWindow* parent,
 111                          wxWindowID id = wxID_ANY);
 112     const wxSize& size = wxDefaultSize, long style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxCLOSE_BOX)
 113     wxSymbolPickerDialog();
 114     //@}
 115
 116     /**
 117         ,  wxPoint&@e pos = wxDefaultPosition,  wxSize&@e size = wxDefaultSize, @b
 118         long@e style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxCLOSE_BOX)
 119         Creation: see @ref wxsymbolpickerdialog() "the constructor" for details about
 120         the parameters.
 121     */
 122     bool Create(const wxString& symbol, const wxString& initialFont,
 123                 const wxString& normalTextFont,
 124                 wxWindow* parent,
 125                 wxWindowID id = wxID_ANY) const;
 126
 127     /**
 128         Returns the font name (the font reflected in the font list).
 129     */
 130     wxString GetFontName() const;
 131
 132     /**
 133         Returns @true if the dialog is showing the full range of Unicode characters.
 134     */
 135     bool GetFromUnicode() const;
 136
 137     /**
 138         Gets the font name used for displaying symbols in the absence of a selected
 139         font.
 140     */
 141     wxString GetNormalTextFontName() const;
 142
 143     /**
 144         Gets the current or initial symbol as a string.
 145     */
 146     wxString GetSymbol() const;
 147
 148     /**
 149         Gets the selected symbol character as an integer.
 150     */
 151     int GetSymbolChar() const;
 152
 153     /**
 154         Returns @true if a symbol is selected.
 155     */
 156     bool HasSelection() const;
 157
 158     /**
 159         Sets the initial/selected font name.
 160     */
 161     void SetFontName(const wxString& value);
 162
 163     /**
 164         Sets the internal flag indicating that the full Unicode range should be
 165         displayed.
 166     */
 167     void SetFromUnicode(bool value);
 168
 169     /**
 170         Sets the name of the font to be used in the absence of a selected font.
 171     */
 172     void SetNormalTextFontName(const wxString& value);
 173
 174     /**
 175         Sets the symbol as a one or zero character string.
 176     */
 177     void SetSymbol(const wxString& value);
 178
 179     /**
 180         Sets Unicode display mode.
 181     */
 182     void SetUnicodeMode(bool unicodeMode);
 183
 184     /**
 185         Returns @true if the has specified normal text - that is, there is no selected
 186         font.
 187     */
 188     bool UseNormalFont() const;
 189 };
 190