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