interface/wx/caret.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        caret.h
   3 // Purpose:     interface of wxCaret
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxCaret
  11
  12     A caret is a blinking cursor showing the position where the typed text will
  13     appear. Text controls usually have their own caret but wxCaret provides a
  14     way to use a caret in other windows.
  15
  16     Currently, the caret appears as a rectangle of the given size. In the
  17     future, it will be possible to specify a bitmap to be used for the caret
  18     shape.
  19
  20     A caret is always associated with a window and the current caret can be
  21     retrieved using wxWindow::GetCaret(). The same caret can't be reused in two
  22     different windows.
  23
  24     @library{wxcore}
  25     @category{misc}
  26 */
  27 class wxCaret
  28 {
  29 public:
  30     /**
  31         Default constructor.
  32     */
  33     wxCaret();
  34
  35     //@{
  36     /**
  37         Creates a caret with the given size (in pixels) and associates it with
  38         the @a window.
  39     */
  40     wxCaret(wxWindow* window, int width, int height);
  41     wxCaret(wxWindowBase* window, const wxSize& size);
  42     //@}
  43
  44     //@{
  45     /**
  46         Creates a caret with the given size (in pixels) and associates it with
  47         the @a window (same as the equivalent constructors).
  48     */
  49     bool Create(wxWindowBase* window, int width, int height);
  50     bool Create(wxWindowBase* window, const wxSize& size);
  51     //@}
  52
  53     /**
  54         Returns the blink time which is measured in milliseconds and is the
  55         time elapsed between 2 inversions of the caret (blink time of the caret
  56         is the same for all carets, so this functions is static).
  57     */
  58     static int GetBlinkTime();
  59
  60     //@{
  61     /**
  62         Get the caret position (in pixels).
  63
  64         @beginWxPerlOnly
  65         In wxPerl there are two methods instead of a single overloaded
  66         method:
  67         - GetPosition(): returns a Wx::Point object.
  68         - GetPositionXY(): returns a 2-element list (x, y).
  69         @endWxPerlOnly
  70     */
  71     void GetPosition(int* x, int* y) const;
  72     wxPoint GetPosition() const;
  73     //@}
  74
  75     //@{
  76     /**
  77         Get the caret size.
  78
  79         @beginWxPerlOnly
  80         In wxPerl there are two methods instead of a single overloaded
  81         method:
  82         - GetSize(): returns a Wx::Size object.
  83         - GetSizeWH(): returns a 2-element list (width, height).
  84         @endWxPerlOnly
  85     */
  86     void GetSize(int* width, int* height) const;
  87     wxSize GetSize() const;
  88     //@}
  89
  90     /**
  91         Get the window the caret is associated with.
  92     */
  93     wxWindow* GetWindow() const;
  94
  95     /**
  96         Hides the caret, same as Show(@false).
  97     */
  98     virtual void Hide();
  99
 100     /**
 101         Returns @true if the caret was created successfully.
 102     */
 103     bool IsOk() const;
 104
 105     /**
 106         Returns @true if the caret is visible and @false if it is permanently
 107         hidden (if it is is blinking and not shown currently but will be after
 108         the next blink, this method still returns @true).
 109     */
 110     bool IsVisible() const;
 111
 112     //@{
 113     /**
 114         Move the caret to given position (in logical coordinates).
 115     */
 116     void Move(int x, int y);
 117     void Move(const wxPoint& pt);
 118     //@}
 119
 120     /**
 121         Sets the blink time for all the carets.
 122
 123         @warning Under Windows, this function will change the blink time for
 124                  all carets permanently (until the next time it is called),
 125                  even for carets in other applications.
 126
 127         @see GetBlinkTime()
 128     */
 129     static void SetBlinkTime(int milliseconds);
 130
 131     //@{
 132     /**
 133         Changes the size of the caret.
 134     */
 135     void SetSize(int width, int height);
 136     void SetSize(const wxSize& size);
 137     //@}
 138
 139     /**
 140         Shows or hides the caret. Notice that if the caret was hidden N times,
 141         it must be shown N times as well to reappear on the screen.
 142     */
 143     virtual void Show(bool show = true);
 144 };
 145