1///////////////////////////////////////////////////////////////////////////////
2// Name:        wx/caret.h
3// Purpose:     wxCaretBase class - the interface of wxCaret
4// Author:      Vadim Zeitlin
5// Modified by:
6// Created:     23.05.99
7// RCS-ID:      $Id: caret.h 49804 2007-11-10 01:09:42Z VZ $
8// Copyright:   (c) wxWidgets team
9// Licence:     wxWindows licence
10///////////////////////////////////////////////////////////////////////////////
11
12#ifndef _WX_CARET_H_BASE_
13#define _WX_CARET_H_BASE_
14
15#include "wx/defs.h"
16
17#if wxUSE_CARET
18
19// ---------------------------------------------------------------------------
20// forward declarations
21// ---------------------------------------------------------------------------
22
23class WXDLLIMPEXP_FWD_CORE wxWindow;
24class WXDLLIMPEXP_FWD_CORE wxWindowBase;
25
26// ----------------------------------------------------------------------------
27// headers we have to include
28// ----------------------------------------------------------------------------
29
30#include "wx/gdicmn.h"  // for wxPoint, wxSize
31
32// ----------------------------------------------------------------------------
33// A caret is a blinking cursor showing the position where the typed text will
34// appear. It can be either a solid block or a custom bitmap (TODO)
35// ----------------------------------------------------------------------------
36
37class WXDLLEXPORT wxCaretBase
38{
39public:
40    // ctors
41    // -----
42        // default - use Create
43    wxCaretBase() { Init(); }
44        // create the caret of given (in pixels) width and height and associate
45        // with the given window
46    wxCaretBase(wxWindowBase *window, int width, int height)
47    {
48        Init();
49
50        (void)Create(window, width, height);
51    }
52        // same as above
53    wxCaretBase(wxWindowBase *window, const wxSize& size)
54    {
55        Init();
56
57        (void)Create(window, size);
58    }
59
60    // a virtual dtor has been provided since this class has virtual members
61    virtual ~wxCaretBase() { }
62
63    // Create() functions - same as ctor but returns the success code
64    // --------------------------------------------------------------
65
66        // same as ctor
67    bool Create(wxWindowBase *window, int width, int height)
68        { return DoCreate(window, width, height); }
69        // same as ctor
70    bool Create(wxWindowBase *window, const wxSize& size)
71        { return DoCreate(window, size.x, size.y); }
72
73    // accessors
74    // ---------
75
76        // is the caret valid?
77    bool IsOk() const { return m_width != 0 && m_height != 0; }
78
79        // is the caret currently shown?
80    bool IsVisible() const { return m_countVisible > 0; }
81
82        // get the caret position
83    void GetPosition(int *x, int *y) const
84    {
85        if ( x ) *x = m_x;
86        if ( y ) *y = m_y;
87    }
88    wxPoint GetPosition() const { return wxPoint(m_x, m_y); }
89
90        // get the caret size
91    void GetSize(int *width, int *height) const
92    {
93        if ( width ) *width = m_width;
94        if ( height ) *height = m_height;
95    }
96    wxSize GetSize() const { return wxSize(m_width, m_height); }
97
98        // get the window we're associated with
99    wxWindow *GetWindow() const { return (wxWindow *)m_window; }
100
101        // change the size of the caret
102    void SetSize(int width, int height) {
103        m_width = width;
104        m_height = height;
105        DoSize();
106    }
107    void SetSize(const wxSize& size) { SetSize(size.x, size.y); }
108
109
110    // operations
111    // ----------
112
113        // move the caret to given position (in logical coords)
114    void Move(int x, int y) { m_x = x; m_y = y; DoMove(); }
115    void Move(const wxPoint& pt) { m_x = pt.x; m_y = pt.y; DoMove(); }
116
117        // show/hide the caret (should be called by wxWindow when needed):
118        // Show() must be called as many times as Hide() + 1 to make the caret
119        // visible
120    virtual void Show(bool show = true)
121        {
122            if ( show )
123            {
124                if ( m_countVisible++ == 0 )
125                    DoShow();
126            }
127            else
128            {
129                if ( --m_countVisible == 0 )
130                    DoHide();
131            }
132        }
133    virtual void Hide() { Show(false); }
134
135        // blink time is measured in milliseconds and is the time elapsed
136        // between 2 inversions of the caret (blink time of the caret is common
137        // to all carets in the Universe, so these functions are static)
138    static int GetBlinkTime();
139    static void SetBlinkTime(int milliseconds);
140
141    // implementation from now on
142    // --------------------------
143
144    // these functions should be called by wxWindow when the window gets/loses
145    // the focus - we create/show and hide/destroy the caret here
146    virtual void OnSetFocus() { }
147    virtual void OnKillFocus() { }
148
149protected:
150    // these functions may be overriden in the derived classes, but they
151    // should call the base class version first
152    virtual bool DoCreate(wxWindowBase *window, int width, int height)
153    {
154        m_window = window;
155        m_width = width;
156        m_height = height;
157
158        return true;
159    }
160
161    // pure virtuals to implement in the derived class
162    virtual void DoShow() = 0;
163    virtual void DoHide() = 0;
164    virtual void DoMove() = 0;
165    virtual void DoSize() { }
166
167    // the common initialization
168    void Init()
169    {
170        m_window = (wxWindowBase *)NULL;
171        m_x = m_y = 0;
172        m_width = m_height = 0;
173        m_countVisible = 0;
174    }
175
176    // the size of the caret
177    int m_width, m_height;
178
179    // the position of the caret
180    int m_x, m_y;
181
182    // the window we're associated with
183    wxWindowBase *m_window;
184
185    // visibility count: the caret is visible only if it's positive
186    int m_countVisible;
187
188private:
189    DECLARE_NO_COPY_CLASS(wxCaretBase)
190};
191
192// ---------------------------------------------------------------------------
193// now include the real thing
194// ---------------------------------------------------------------------------
195
196#if defined(__WXMSW__)
197    #include "wx/msw/caret.h"
198#else
199    #include "wx/generic/caret.h"
200#endif // platform
201
202// ----------------------------------------------------------------------------
203// wxCaretSuspend: a simple class which hides the caret in its ctor and
204// restores it in the dtor, this should be used when drawing on the screen to
205// avoid overdrawing the caret
206// ----------------------------------------------------------------------------
207
208#ifdef wxHAS_CARET_USING_OVERLAYS
209
210// we don't need to hide the caret if it's rendered using overlays
211class WXDLLEXPORT wxCaretSuspend
212{
213public:
214    wxCaretSuspend(wxWindow *WXUNUSED(win)) {}
215
216    DECLARE_NO_COPY_CLASS(wxCaretSuspend)
217};
218
219#else // !wxHAS_CARET_USING_OVERLAYS
220
221class WXDLLEXPORT wxCaretSuspend
222{
223public:
224    wxCaretSuspend(wxWindow *win)
225    {
226        m_caret = win->GetCaret();
227        m_show = false;
228        if ( m_caret && m_caret->IsVisible() )
229        {
230            m_caret->Hide();
231            m_show = true;
232        }
233    }
234
235    ~wxCaretSuspend()
236    {
237        if ( m_caret && m_show )
238            m_caret->Show();
239    }
240
241private:
242    wxCaret *m_caret;
243    bool     m_show;
244
245    DECLARE_NO_COPY_CLASS(wxCaretSuspend)
246};
247
248#endif // wxHAS_CARET_USING_OVERLAYS/!wxHAS_CARET_USING_OVERLAYS
249
250#endif // wxUSE_CARET
251
252#endif // _WX_CARET_H_BASE_
253