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     void GetPosition(int* x, int* y) const;
  65     wxPoint GetPosition() const;
  66     //@}
  67
  68     //@{
  69     /**
  70         Get the caret size.
  71     */
  72     void GetSize(int* width, int* height) const;
  73     wxSize GetSize() const;
  74     //@}
  75
  76     /**
  77         Get the window the caret is associated with.
  78     */
  79     wxWindow* GetWindow() const;
  80
  81     /**
  82         Hides the caret, same as Show(@false).
  83     */
  84     virtual void Hide();
  85
  86     /**
  87         Returns @true if the caret was created successfully.
  88     */
  89     bool IsOk() const;
  90
  91     /**
  92         Returns @true if the caret is visible and @false if it is permanently
  93         hidden (if it is is blinking and not shown currently but will be after
  94         the next blink, this method still returns @true).
  95     */
  96     bool IsVisible() const;
  97
  98     //@{
  99     /**
 100         Move the caret to given position (in logical coordinates).
 101     */
 102     void Move(int x, int y);
 103     void Move(const wxPoint& pt);
 104     //@}
 105
 106     /**
 107         Sets the blink time for all the carets.
 108
 109         @warning Under Windows, this function will change the blink time for
 110                  all carets permanently (until the next time it is called),
 111                  even for carets in other applications.
 112
 113         @see GetBlinkTime()
 114     */
 115     static void SetBlinkTime(int milliseconds);
 116
 117     //@{
 118     /**
 119         Changes the size of the caret.
 120     */
 121     void SetSize(int width, int height);
 122     void SetSize(const wxSize& size);
 123     //@}
 124
 125     /**
 126         Shows or hides the caret. Notice that if the caret was hidden N times,
 127         it must be shown N times as well to reappear on the screen.
 128     */
 129     virtual void Show(bool show = true);
 130 };
 131