include/wx/caret.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        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$
   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
  23 class WXDLLEXPORT wxWindow;
  24 class WXDLLEXPORT 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
  37 class WXDLLEXPORT wxCaretBase
  38 {
  39 public:
  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
 149 protected:
 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
 188 private:
 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 class WXDLLEXPORT wxCaretSuspend
 209 {
 210 public:
 211     wxCaretSuspend(wxWindow *win)
 212     {
 213         m_caret = win->GetCaret();
 214         m_show = false;
 215         if ( m_caret && m_caret->IsVisible() )
 216         {
 217             m_caret->Hide();
 218             m_show = true;
 219         }
 220     }
 221
 222     ~wxCaretSuspend()
 223     {
 224         if ( m_caret && m_show )
 225             m_caret->Show();
 226     }
 227
 228 private:
 229     wxCaret *m_caret;
 230     bool     m_show;
 231
 232     DECLARE_NO_COPY_CLASS(wxCaretSuspend)
 233 };
 234
 235 #endif // wxUSE_CARET
 236
 237 #endif // _WX_CARET_H_BASE_
 238