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