interface/richtext/richtextsymboldlg.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        richtext/richtextsymboldlg.h
   3 // Purpose:     documentation for wxSymbolPickerDialog class
   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 empty
  87         string.
  88
  89         @param initialFont
  90         The initial font to be displayed in the font list. If empty, the item normal
  91         text will be selected.
  92
  93         @param normalTextFont
  94         The font the dialog will use to display the symbols if the initial font is
  95         empty.
  96
  97         @param parent
  98         The dialog's parent.
  99
 100         @param id
 101         The dialog's identifier.
 102
 103         @param title
 104         The dialog's caption.
 105
 106         @param pos
 107         The dialog's position.
 108
 109         @param size
 110         The dialog's size.
 111
 112         @param style
 113         The dialog's window style.
 114     */
 115     wxSymbolPickerDialog(const wxString& symbol,
 116                          const wxString& initialFont,
 117                          const wxString& normalTextFont,
 118                          wxWindow* parent,
 119                          wxWindowID id = wxID_ANY);
 120         const wxSize& size = wxDefaultSize, long style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxCLOSE_BOX)
 121  wxSymbolPickerDialog();
 122     //@}
 123
 124     /**
 125         , @b const wxPoint&@e pos = wxDefaultPosition, @b const wxSize&@e size =
 126         wxDefaultSize, @b long@e style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxCLOSE_BOX)
 127
 128         Creation: see @ref wxsymbolpickerdialog() "the constructor" for details about
 129         the parameters.
 130     */
 131     bool Create(const wxString& symbol, const wxString& initialFont,
 132                 const wxString& normalTextFont,
 133                 wxWindow* parent,
 134                 wxWindowID id = wxID_ANY);
 135
 136     /**
 137         Returns the font name (the font reflected in the font list).
 138     */
 139     wxString GetFontName();
 140
 141     /**
 142         Returns @true if the dialog is showing the full range of Unicode characters.
 143     */
 144     bool GetFromUnicode();
 145
 146     /**
 147         Gets the font name used for displaying symbols in the absence of a selected
 148         font.
 149     */
 150     wxString GetNormalTextFontName();
 151
 152     /**
 153         Gets the current or initial symbol as a string.
 154     */
 155     wxString GetSymbol();
 156
 157     /**
 158         Gets the selected symbol character as an integer.
 159     */
 160     int GetSymbolChar();
 161
 162     /**
 163         Returns @true if a symbol is selected.
 164     */
 165     bool HasSelection();
 166
 167     /**
 168         Sets the initial/selected font name.
 169     */
 170     void SetFontName(const wxString& value);
 171
 172     /**
 173         Sets the internal flag indicating that the full Unicode range should be
 174         displayed.
 175     */
 176     void SetFromUnicode(bool value);
 177
 178     /**
 179         Sets the name of the font to be used in the absence of a selected font.
 180     */
 181     void SetNormalTextFontName(const wxString& value);
 182
 183     /**
 184         Sets the symbol as a one or zero character string.
 185     */
 186     void SetSymbol(const wxString& value);
 187
 188     /**
 189         Sets Unicode display mode.
 190     */
 191     void SetUnicodeMode(bool unicodeMode);
 192
 193     /**
 194         Returns @true if the has specified normal text - that is, there is no selected
 195         font.
 196     */
 197     bool UseNormalFont();
 198 };