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