]> git.saurik.com Git - wxWidgets.git/blame_incremental - interface/wx/caret.h
do not use @b when referencing to functions; use final () to enable doxygen autolink
[wxWidgets.git] / interface / wx / caret.h
... / ...
CommitLineData
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*/
27class wxCaret
28{
29public:
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 const wxPoint GetPosition() const;
66 //@}
67
68 //@{
69 /**
70 Get the caret size.
71 */
72 void GetSize(int* width, int* height) const;
73 const 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