interface/wx/richtext/richtextsymboldlg.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        richtext/richtextsymboldlg.h
   3 // Purpose:     interface of wxSymbolPickerDialog
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     @class wxSymbolPickerDialog
  10
  11     wxSymbolPickerDialog presents the user with a choice of fonts and a grid
  12     of available characters. This modal dialog provides the application with
  13     a selected symbol and optional font selection.
  14
  15     Although this dialog is contained in the rich text library, the dialog
  16     is generic and can be used in other contexts.
  17
  18     To use the dialog, pass a default symbol specified as a string, an initial font
  19     name, and a current font name. The difference between the initial font and
  20     current font is that the initial font determines what the font control will be
  21     set to when the dialog shows - an empty string will show the selection
  22     @e normal text.
  23     The current font, on the other hand, is used by the dialog to determine what
  24     font to display the characters in, even when no initial font is selected.
  25     This allows the user (and application) to distinguish between inserting a
  26     symbol in the current font, and inserting it with a specified font.
  27
  28     When the dialog is dismissed, the application can get the selected symbol
  29     with wxSymbolPickerDialog::GetSymbol and test whether a font was specified
  30     with wxSymbolPickerDialog::UseNormalFont,fetching the specified font with
  31     wxSymbolPickerDialog::GetFontName.
  32
  33     Here's a realistic example, inserting the supplied symbol into a
  34     rich text control in either the current font or specified font.
  35
  36     @code
  37         wxRichTextCtrl* ctrl = (wxRichTextCtrl*) FindWindow(ID_RICHTEXT_CTRL);
  38
  39         wxTextAttr attr;
  40         attr.SetFlags(wxTEXT_ATTR_FONT);
  41         ctrl-GetStyle(ctrl->GetInsertionPoint(), attr);
  42
  43         wxString currentFontName;
  44         if (attr.HasFont() && attr.GetFont().IsOk())
  45             currentFontName = attr.GetFont().GetFaceName();
  46
  47         // Don't set the initial font in the dialog (so the user is choosing
  48         // 'normal text', i.e. the current font) but do tell the dialog
  49         // what 'normal text' is.
  50
  51         wxSymbolPickerDialog dlg("*", wxEmptyString, currentFontName, this);
  52
  53         if (dlg.ShowModal() == wxID_OK)
  54         {
  55             if (dlg.HasSelection())
  56             {
  57                 long insertionPoint = ctrl-GetInsertionPoint();
  58
  59                 ctrl->WriteText(dlg.GetSymbol());
  60
  61                 if (!dlg.UseNormalFont())
  62                 {
  63                     wxFont font(attr.GetFont());
  64                     font.SetFaceName(dlg.GetFontName());
  65                     attr.SetFont(font);
  66                     ctrl-SetStyle(insertionPoint, insertionPoint+1, attr);
  67                 }
  68             }
  69         }
  70     @endcode
  71
  72     @library{wxrichtext}
  73     @category{cmndlg}
  74 */
  75 class wxSymbolPickerDialog : public wxDialog
  76 {
  77 public:
  78     /**
  79         Default ctor.
  80     */
  81     wxSymbolPickerDialog();
  82
  83     /**
  84         Constructor.
  85
  86         @param symbol
  87             The initial symbol to show.
  88             Specify a single character in a string, or an empty string.
  89         @param initialFont
  90             The initial font to be displayed in the font list.
  91             If empty, the item normal text will be selected.
  92         @param normalTextFont
  93             The font the dialog will use to display the symbols if the
  94             initial font is empty.
  95         @param parent
  96             The dialog's parent.
  97         @param id
  98             The dialog's identifier.
  99         @param title
 100             The dialog's caption.
 101         @param pos
 102             The dialog's position.
 103         @param size
 104             The dialog's size.
 105         @param style
 106             The dialog's window style.
 107     */
 108     wxSymbolPickerDialog(const wxString& symbol,
 109                          const wxString& initialFont,
 110                          const wxString& normalTextFont,
 111                          wxWindow* parent,
 112                          wxWindowID id = wxID_ANY,
 113                          const wxString& title = _("Symbols"),
 114                          const wxPoint& pos = wxDefaultPosition,
 115                          const wxSize& size = wxDefaultSize,
 116                          long style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxCLOSE_BOX);
 117
 118     /**
 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, wxWindow* parent,
 124                 wxWindowID id = wxID_ANY,
 125                 const wxString& caption = wxGetTranslation("Symbols"), const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxSize(400, 300), long style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxCLOSE_BOX);
 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 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(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(wxString value);
 172
 173     /**
 174         Sets the symbol as a one or zero character string.
 175     */
 176     void SetSymbol(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 font.
 185     */
 186     bool UseNormalFont() const;
 187 };
 188