interface/caret.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        caret.h
   3 // Purpose:     documentation for wxCaret class
   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     @seealso
  28     wxCaret::GetBlinkTime
  29 */
  30 class wxCaret
  31 {
  32 public:
  33     //@{
  34     /**
  35         Create the caret of given (in pixels) width and height and associates it
  36         with the given window.
  37     */
  38     wxCaret();
  39     wxCaret(wxWindow* window, int width, int height);
  40     wxCaret(wxWindowBase* window, const wxSize& size);
  41     //@}
  42
  43     //@{
  44     /**
  45         Create the caret of given (in pixels) width and height and associates it
  46         with the given window (same as constructor).
  47     */
  48     bool Create(wxWindowBase* window, int width, int height);
  49     bool Create(wxWindowBase* window, const wxSize& size);
  50     //@}
  51
  52     /**
  53         Returns the blink time which is measured in milliseconds and is the time elapsed
  54         between 2 inversions of the caret (blink time of the caret is the same
  55         for all carets, so this functions is static).
  56     */
  57     static int GetBlinkTime();
  58
  59     //@{
  60     /**
  61         Get the caret position (in pixels).
  62
  63
  64
  65         @b GetPosition()
  66
  67
  68         Returns a Wx::Point
  69
  70         @b GetPositionXY()
  71
  72
  73         Returns a 2-element list
  74          @c ( x, y )
  75     */
  76     void GetPosition(int* x, int* y);
  77     wxPoint GetPosition();
  78     //@}
  79
  80     //@{
  81     /**
  82         Get the caret size.
  83
  84
  85
  86         @b GetSize()
  87
  88
  89         Returns a Wx::Size
  90
  91         @b GetSizeWH()
  92
  93
  94         Returns a 2-element list
  95          @c ( width, height )
  96     */
  97     void GetSize(int* width, int* height);
  98     wxSize GetSize();
  99     //@}
 100
 101     /**
 102         Get the window the caret is associated with.
 103     */
 104     wxWindow* GetWindow();
 105
 106     /**
 107         Same as wxCaret::Show(@false).
 108     */
 109     void Hide();
 110
 111     /**
 112         Returns @true if the caret was created successfully.
 113     */
 114 #define bool IsOk()     /* implementation is private */
 115
 116     /**
 117         Returns @true if the caret is visible and @false if it is permanently
 118         hidden (if it is is blinking and not shown currently but will be after the
 119         next blink, this method still returns @true).
 120     */
 121     bool IsVisible();
 122
 123     //@{
 124     /**
 125         Move the caret to given position (in logical coordinates).
 126     */
 127     void Move(int x, int y);
 128     void Move(const wxPoint& pt);
 129     //@}
 130
 131     /**
 132         Sets the blink time for all the carets.
 133
 134         @remarks Under Windows, this function will change the blink time for all
 135                    carets permanently (until the next time it is
 136                    called), even for the carets in other applications.
 137
 138         @sa GetBlinkTime()
 139     */
 140     static void SetBlinkTime(int milliseconds);
 141
 142     //@{
 143     /**
 144         Changes the size of the caret.
 145     */
 146     void SetSize(int width, int height);
 147     void SetSize(const wxSize& size);
 148     //@}
 149
 150     /**
 151         Shows or hides the caret. Notice that if the caret was hidden N times, it
 152         must be shown N times as well to reappear on the screen.
 153     */
 154     void Show(bool show = @true);
 155 };