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