]> git.saurik.com Git - wxWidgets.git/blobdiff - src/common/wincmn.cpp
wxMotif compilation fixes for wxDataObject and PROCESS_EVENTS (wxSocket)
[wxWidgets.git] / src / common / wincmn.cpp
index 611ab2b4c0b0947c21bb5397d18251b05400167d..ccba8e7c5370a7fddc60655c643d672706ffb163 100644 (file)
@@ -43,6 +43,7 @@
 
 #if wxUSE_CONSTRAINTS
     #include "wx/layout.h"
+    #include "wx/sizer.h"
 #endif // wxUSE_CONSTRAINTS
 
 #if wxUSE_DRAG_AND_DROP
     #include "wx/tooltip.h"
 #endif // wxUSE_TOOLTIPS
 
+#if wxUSE_CARET
+    #include "wx/caret.h"
+#endif // wxUSE_CARET
+
 // ----------------------------------------------------------------------------
 // static data
 // ----------------------------------------------------------------------------
 
-int wxWindowBase::ms_lastControlId = 0;
+int wxWindowBase::ms_lastControlId = -200;
 
 IMPLEMENT_ABSTRACT_CLASS(wxWindowBase, wxEvtHandler)
 
@@ -96,15 +101,17 @@ void wxWindowBase::InitBase()
     m_isShown = FALSE;
     m_isEnabled = TRUE;
 
-    // no client data
-    m_clientObject = (wxClientData *)NULL;
+    // no client data (yet)
     m_clientData = NULL;
+    m_clientDataType = ClientData_None;
 
     // the default event handler is just this window
     m_eventHandler = this;
 
+#if wxUSE_VALIDATORS
     // no validator
     m_windowValidator = (wxValidator *) NULL;
+#endif // wxUSE_VALIDATORS
 
     // use the system default colours
     wxSystemSettings settings;
@@ -125,7 +132,6 @@ void wxWindowBase::InitBase()
     m_constraints = (wxLayoutConstraints *) NULL;
     m_constraintsInvolvedIn = (wxWindowList *) NULL;
     m_windowSizer = (wxSizer *) NULL;
-    m_sizerParent = (wxWindowBase *) NULL;
     m_autoLayout = FALSE;
 #endif // wxUSE_CONSTRAINTS
 
@@ -136,6 +142,10 @@ void wxWindowBase::InitBase()
 #if wxUSE_TOOLTIPS
     m_tooltip = (wxToolTip *)NULL;
 #endif // wxUSE_TOOLTIPS
+
+#if wxUSE_CARET
+    m_caret = (wxCaret *)NULL;
+#endif // wxUSE_CARET
 }
 
 // common part of window creation process
@@ -144,12 +154,13 @@ bool wxWindowBase::CreateBase(wxWindowBase *parent,
                               const wxPoint& WXUNUSED(pos),
                               const wxSize& WXUNUSED(size),
                               long style,
+                              const wxValidator& validator,
                               const wxString& name)
 {
     // m_isWindow is set to TRUE in wxWindowBase::Init() as well as many other
     // member variables - check that it has been called (will catch the case
     // when a new ctor is added which doesn't call InitWindow)
-    wxASSERT_MSG( m_isWindow, _T("Init() must have been called before!") );
+    wxASSERT_MSG( m_isWindow, wxT("Init() must have been called before!") );
 
     // generate a new id if the user doesn't care about it
     m_windowId = id == -1 ? NewControlId() : id;
@@ -157,6 +168,7 @@ bool wxWindowBase::CreateBase(wxWindowBase *parent,
     SetName(name);
     SetWindowStyleFlag(style);
     SetParent(parent);
+    SetValidator(validator);
 
     return TRUE;
 }
@@ -178,13 +190,31 @@ wxWindowBase::~wxWindowBase()
     // Just in case we've loaded a top-level window via LoadNativeDialog but
     // we weren't a dialog class
     wxTopLevelWindows.DeleteObject(this);
-    
-    wxASSERT_MSG( GetChildren().GetCount() == 0, "children not destroyed" );
 
+    wxASSERT_MSG( GetChildren().GetCount() == 0, wxT("children not destroyed") );
+
+    // make sure that there are no dangling pointers left pointing to us
+    wxPanel *panel = wxDynamicCast(GetParent(), wxPanel);
+    if ( panel )
+    {
+        if ( panel->GetLastFocus() == this )
+        {
+            panel->SetLastFocus((wxWindow *)NULL);
+        }
+    }
+
+#if wxUSE_CARET
+    if ( m_caret )
+        delete m_caret;
+#endif // wxUSE_CARET
+
+#if wxUSE_VALIDATORS
     if ( m_windowValidator )
         delete m_windowValidator;
+#endif // wxUSE_VALIDATORS
 
-    if ( m_clientObject )
+    // we only delete object data, not untyped
+    if ( m_clientDataType == ClientData_Object )
         delete m_clientObject;
 
 #if wxUSE_CONSTRAINTS
@@ -204,9 +234,6 @@ wxWindowBase::~wxWindowBase()
     if ( m_windowSizer )
         delete m_windowSizer;
 
-    // If this is a child of a sizer, remove self from parent
-    if ( m_sizerParent )
-        m_sizerParent->RemoveChild(this);
 #endif // wxUSE_CONSTRAINTS
 
 #if wxUSE_DRAG_AND_DROP
@@ -244,15 +271,21 @@ bool wxWindowBase::Close(bool force)
 bool wxWindowBase::DestroyChildren()
 {
     wxWindowList::Node *node;
-    while ( (node = GetChildren().GetFirst()) )
+    for ( ;; )
     {
+        // we iterate until the list becomes empty
+        node = GetChildren().GetFirst();
+        if ( !node )
+            break;
+
         wxWindow *child = node->GetData();
-       
-       wxASSERT_MSG( child, "m_children contains empty nodes" );
-       
+
+        wxASSERT_MSG( child, wxT("children list contains empty nodes") );
+
         delete child;
-       
-        wxASSERT_MSG( !GetChildren().Find(child), "child didn't remove itself using RemoveChild()" );
+
+        wxASSERT_MSG( !GetChildren().Find(child),
+                      wxT("child didn't remove itself using RemoveChild()") );
     }
 
     return TRUE;
@@ -268,29 +301,50 @@ void wxWindowBase::Centre(int direction)
     int widthParent, heightParent;
 
     wxWindow *parent = GetParent();
-    if ( parent )
+    if ( !parent )
     {
-        parent->GetClientSize(&widthParent, &heightParent);
+        // no other choice
+        direction |= wxCENTRE_ON_SCREEN;
     }
-    else
+
+    if ( direction & wxCENTRE_ON_SCREEN )
     {
         // centre with respect to the whole screen
         wxDisplaySize(&widthParent, &heightParent);
     }
+    else
+    {
+        // centre inside the parents rectangle
+        parent->GetClientSize(&widthParent, &heightParent);
+    }
 
     int width, height;
     GetSize(&width, &height);
 
-    int new_x = -1,
-        new_y = -1;
+    int xNew = -1,
+        yNew = -1;
 
     if ( direction & wxHORIZONTAL )
-        new_x = (widthParent - width)/2;
+        xNew = (widthParent - width)/2;
 
     if ( direction & wxVERTICAL )
-        new_y = (heightParent - height)/2;
+        yNew = (heightParent - height)/2;
+
+    // controls are always centered on their parent because it doesn't make
+    // sense to centre them on the screen
+    if ( !(direction & wxCENTRE_ON_SCREEN) || wxDynamicCast(this, wxControl) )
+    {
+        // theo nly chance to get this is to have a wxControl without parent
+        wxCHECK_RET( parent, wxT("a control must have a parent") );
+
+        // adjust to the parents client area origin
+        wxPoint posParent = parent->ClientToScreen(wxPoint(0, 0));
 
-    Move(new_x, new_y);
+        xNew += posParent.x;
+        yNew += posParent.y;
+    }
+
+    Move(xNew, yNew);
 }
 
 // fits the window around the children
@@ -299,10 +353,18 @@ void wxWindowBase::Fit()
     int maxX = 0,
         maxY = 0;
 
-    wxWindowList::Node *node = GetChildren().GetFirst();
-    while ( node )
+    for ( wxWindowList::Node *node = GetChildren().GetFirst();
+          node;
+          node = node->GetNext() )
     {
         wxWindow *win = node->GetData();
+        if ( win->IsTopLevel() )
+        {
+            // dialogs and frames lie in different top level windows - don't
+            // deal with them here
+            continue;
+        }
+
         int wx, wy, ww, wh;
         win->GetPosition(&wx, &wy);
         win->GetSize(&ww, &wh);
@@ -310,8 +372,6 @@ void wxWindowBase::Fit()
             maxX = wx + ww;
         if ( wy + wh > maxY )
             maxY = wy + wh;
-
-        node = node->GetNext();
     }
 
     // leave a margin
@@ -361,6 +421,14 @@ bool wxWindowBase::Enable(bool enable)
         return FALSE;
     }
 }
+// ----------------------------------------------------------------------------
+// RTTI
+// ----------------------------------------------------------------------------
+
+bool wxWindowBase::IsTopLevel() const
+{
+    return wxDynamicCast(this, wxFrame) || wxDynamicCast(this, wxDialog);
+}
 
 // ----------------------------------------------------------------------------
 // reparenting the window
@@ -368,7 +436,7 @@ bool wxWindowBase::Enable(bool enable)
 
 void wxWindowBase::AddChild(wxWindowBase *child)
 {
-    wxCHECK_RET( child, _T("can't add a NULL child") );
+    wxCHECK_RET( child, wxT("can't add a NULL child") );
 
     GetChildren().Append(child);
     child->SetParent(this);
@@ -376,7 +444,7 @@ void wxWindowBase::AddChild(wxWindowBase *child)
 
 void wxWindowBase::RemoveChild(wxWindowBase *child)
 {
-    wxCHECK_RET( child, _T("can't remove a NULL child") );
+    wxCHECK_RET( child, wxT("can't remove a NULL child") );
 
     GetChildren().DeleteObject(child);
     child->SetParent((wxWindow *)NULL);
@@ -471,7 +539,7 @@ bool wxWindowBase::SetCursor(const wxCursor& cursor)
     // don't try to set invalid cursor, always fall back to the default
     const wxCursor& cursorOk = cursor.Ok() ? cursor : *wxSTANDARD_CURSOR;
 
-    if ( cursorOk == m_cursor )
+    if ( (wxCursor&)cursorOk == m_cursor )
     {
         // no change
         return FALSE;
@@ -487,7 +555,7 @@ bool wxWindowBase::SetFont(const wxFont& font)
     // don't try to set invalid font, always fall back to the default
     const wxFont& fontOk = font.Ok() ? font : *wxSWISS_FONT;
 
-    if ( fontOk == m_font )
+    if ( (wxFont&)fontOk == m_font )
     {
         // no change
         return FALSE;
@@ -498,6 +566,25 @@ bool wxWindowBase::SetFont(const wxFont& font)
     return TRUE;
 }
 
+#if wxUSE_CARET
+void wxWindowBase::SetCaret(wxCaret *caret)
+{
+    if ( m_caret )
+    {
+        delete m_caret;
+    }
+
+    m_caret = caret;
+
+    if ( m_caret )
+    {
+        wxASSERT_MSG( m_caret->GetWindow() == this,
+                      wxT("caret should be created associated to this window") );
+    }
+}
+#endif // wxUSE_CARET
+
+#if wxUSE_VALIDATORS
 // ----------------------------------------------------------------------------
 // validators
 // ----------------------------------------------------------------------------
@@ -512,6 +599,7 @@ void wxWindowBase::SetValidator(const wxValidator& validator)
     if ( m_windowValidator )
         m_windowValidator->SetWindow(this) ;
 }
+#endif // wxUSE_VALIDATORS
 
 // ----------------------------------------------------------------------------
 // update region testing
@@ -567,29 +655,44 @@ wxWindow *wxWindowBase::FindWindow( const wxString& name )
 // dialog oriented functions
 // ----------------------------------------------------------------------------
 
-void wxWindowBase::MakeModal(bool WXUNUSED(modal))
+void wxWindowBase::MakeModal(bool modal)
 {
-    wxFAIL_MSG("TODO");
+    // Disable all other windows
+    if ( IsTopLevel() )
+    {
+        wxWindowList::Node *node = wxTopLevelWindows.GetFirst();
+        while (node)
+        {
+            wxWindow *win = node->GetData();
+            if (win != this)
+                win->Enable(!modal);
+
+            node = node->GetNext();
+        }
+    }
 }
 
 bool wxWindowBase::Validate()
 {
+#if wxUSE_VALIDATORS
     wxWindowList::Node *node;
     for ( node = m_children.GetFirst(); node; node = node->GetNext() )
     {
         wxWindowBase *child = node->GetData();
         wxValidator *validator = child->GetValidator();
-        if ( validator && validator->Validate(this) )
+        if ( validator && !validator->Validate((wxWindow *)this) )
         {
             return FALSE;
         }
     }
+#endif // wxUSE_VALIDATORS
 
     return TRUE;
 }
 
 bool wxWindowBase::TransferDataToWindow()
 {
+#if wxUSE_VALIDATORS
     wxWindowList::Node *node;
     for ( node = m_children.GetFirst(); node; node = node->GetNext() )
     {
@@ -607,12 +710,14 @@ bool wxWindowBase::TransferDataToWindow()
             return FALSE;
         }
     }
+#endif // wxUSE_VALIDATORS
 
     return TRUE;
 }
 
 bool wxWindowBase::TransferDataFromWindow()
 {
+#if wxUSE_VALIDATORS
     wxWindowList::Node *node;
     for ( node = m_children.GetFirst(); node; node = node->GetNext() )
     {
@@ -623,6 +728,7 @@ bool wxWindowBase::TransferDataFromWindow()
             return FALSE;
         }
     }
+#endif // wxUSE_VALIDATORS
 
     return TRUE;
 }
@@ -780,39 +886,35 @@ void wxWindowBase::DeleteRelatedConstraints()
 
 void wxWindowBase::SetSizer(wxSizer *sizer)
 {
+    if (m_windowSizer) delete m_windowSizer;
+
     m_windowSizer = sizer;
-    if ( sizer )
-        sizer->SetSizerParent(this);
 }
 
 bool wxWindowBase::Layout()
 {
-    if ( GetConstraints() )
-    {
-        int w, h;
-        GetClientSize(&w, &h);
-        GetConstraints()->width.SetValue(w);
-        GetConstraints()->height.SetValue(h);
-    }
-
-    // If top level (one sizer), evaluate the sizer's constraints.
+    int w, h;
+    GetClientSize(&w, &h);
+    
+    // If there is a sizer, use it instead of the constraints
     if ( GetSizer() )
     {
-        int noChanges;
-        GetSizer()->ResetConstraints();   // Mark all constraints as unevaluated
-        GetSizer()->LayoutPhase1(&noChanges);
-        GetSizer()->LayoutPhase2(&noChanges);
-        GetSizer()->SetConstraintSizes(); // Recursively set the real window sizes
+        GetSizer()->SetDimension( 0, 0, w, h );
         return TRUE;
     }
-    else
+    
+    if ( GetConstraints() )
     {
-        // Otherwise, evaluate child constraints
-        ResetConstraints();   // Mark all constraints as unevaluated
-        DoPhase(1);           // Just one phase need if no sizers involved
-        DoPhase(2);
-        SetConstraintSizes(); // Recursively set the real window sizes
+        GetConstraints()->width.SetValue(w);
+        GetConstraints()->height.SetValue(h);
     }
+       
+    // Evaluate child constraints
+    ResetConstraints();   // Mark all constraints as unevaluated
+    DoPhase(1);           // Just one phase need if no sizers involved
+    DoPhase(2);
+    SetConstraintSizes(); // Recursively set the real window sizes
+    
     return TRUE;
 }
 
@@ -857,7 +959,7 @@ bool wxWindowBase::DoPhase(int phase)
         while (node)
         {
             wxWindow *child = node->GetData();
-            if ( !child->IsKindOf(CLASSINFO(wxFrame)) && !child->IsKindOf(CLASSINFO(wxDialog)) )
+            if ( !child->IsTopLevel() )
             {
                 wxLayoutConstraints *constr = child->GetConstraints();
                 if ( constr )
@@ -901,7 +1003,7 @@ void wxWindowBase::ResetConstraints()
     while (node)
     {
         wxWindow *win = node->GetData();
-        if ( !win->IsKindOf(CLASSINFO(wxFrame)) && !win->IsKindOf(CLASSINFO(wxDialog)) )
+        if ( !win->IsTopLevel() )
             win->ResetConstraints();
         node = node->GetNext();
     }
@@ -920,17 +1022,15 @@ void wxWindowBase::SetConstraintSizes(bool recurse)
         int w = constr->width.GetValue();
         int h = constr->height.GetValue();
 
-        // If we don't want to resize this window, just move it...
         if ( (constr->width.GetRelationship() != wxAsIs ) ||
-                (constr->height.GetRelationship() != wxAsIs))
+             (constr->height.GetRelationship() != wxAsIs) )
         {
-            // Calls Layout() recursively. AAAGH. How can we stop that.
-            // Simply take Layout() out of non-top level OnSizes.
-            SizerSetSize(x, y, w, h);
+            SetSize(x, y, w, h);
         }
         else
         {
-            SizerMove(x, y);
+            // If we don't want to resize this window, just move it...
+            Move(x, y);
         }
     }
     else if ( constr )
@@ -938,18 +1038,18 @@ void wxWindowBase::SetConstraintSizes(bool recurse)
         wxChar *windowClass = GetClassInfo()->GetClassName();
 
         wxString winName;
-        if ( GetName() == _T("") )
-            winName = _T("unnamed");
+        if ( GetName() == wxT("") )
+            winName = wxT("unnamed");
         else
             winName = GetName();
-        wxLogDebug( _T("Constraint(s) not satisfied for window of type %s, name %s:\n"),
+        wxLogDebug( wxT("Constraint(s) not satisfied for window of type %s, name %s:\n"),
                 (const wxChar *)windowClass,
                 (const wxChar *)winName);
-        if ( !constr->left.GetDone()) wxLogDebug( _T("  unsatisfied 'left' constraint.\n")  );
-        if ( !constr->right.GetDone()) wxLogDebug( _T("  unsatisfied 'right' constraint.\n")  );
-        if ( !constr->width.GetDone()) wxLogDebug( _T("  unsatisfied 'width' constraint.\n")  );
-        if ( !constr->height.GetDone())  wxLogDebug( _T("  unsatisfied 'height' constraint.\n")  );
-        wxLogDebug( _T("Please check constraints: try adding AsIs() constraints.\n") );
+        if ( !constr->left.GetDone()) wxLogDebug( wxT("  unsatisfied 'left' constraint.\n")  );
+        if ( !constr->right.GetDone()) wxLogDebug( wxT("  unsatisfied 'right' constraint.\n")  );
+        if ( !constr->width.GetDone()) wxLogDebug( wxT("  unsatisfied 'width' constraint.\n")  );
+        if ( !constr->height.GetDone())  wxLogDebug( wxT("  unsatisfied 'height' constraint.\n")  );
+        wxLogDebug( wxT("Please check constraints: try adding AsIs() constraints.\n") );
     }
 
     if ( recurse )
@@ -958,44 +1058,13 @@ void wxWindowBase::SetConstraintSizes(bool recurse)
         while (node)
         {
             wxWindow *win = node->GetData();
-            if ( !win->IsKindOf(CLASSINFO(wxFrame)) && !win->IsKindOf(CLASSINFO(wxDialog)) )
+            if ( !win->IsTopLevel() )
                 win->SetConstraintSizes();
             node = node->GetNext();
         }
     }
 }
 
-// This assumes that all sizers are 'on' the same window, i.e. the parent of
-// this window.
-void wxWindowBase::TransformSizerToActual(int *x, int *y) const
-{
-    if ( !m_sizerParent || m_sizerParent->IsKindOf(CLASSINFO(wxDialog) ) ||
-            m_sizerParent->IsKindOf(CLASSINFO(wxFrame)) )
-        return;
-
-    int xp, yp;
-    m_sizerParent->GetPosition(&xp, &yp);
-    m_sizerParent->TransformSizerToActual(&xp, &yp);
-    *x += xp;
-    *y += yp;
-}
-
-void wxWindowBase::SizerSetSize(int x, int y, int w, int h)
-{
-    int xx = x;
-    int yy = y;
-    TransformSizerToActual(&xx, &yy);
-    SetSize(xx, yy, w, h);
-}
-
-void wxWindowBase::SizerMove(int x, int y)
-{
-    int xx = x;
-    int yy = y;
-    TransformSizerToActual(&xx, &yy);
-    Move(xx, yy);
-}
-
 // Only set the size/position of the constraint (if any)
 void wxWindowBase::SetSizeConstraint(int x, int y, int w, int h)
 {
@@ -1102,22 +1171,30 @@ void wxWindowBase::UpdateWindowUI()
             if ( event.GetSetEnabled() )
                 Enable(event.GetEnabled());
 
-            if ( event.GetSetText() && IsKindOf(CLASSINFO(wxControl)) )
-                ((wxControl*)this)->SetLabel(event.GetText());
+            if ( event.GetSetText() )
+            {
+                wxControl *control = wxDynamicCast(this, wxControl);
+                if ( control )
+                    control->SetLabel(event.GetText());
+            }
 
-            if ( IsKindOf(CLASSINFO(wxCheckBox)) )
+#if wxUSE_CHECKBOX
+            wxCheckBox *checkbox = wxDynamicCast(this, wxCheckBox);
+            if ( checkbox )
             {
                 if ( event.GetSetChecked() )
-                    ((wxCheckBox *)this)->SetValue(event.GetChecked());
+                    checkbox->SetValue(event.GetChecked());
             }
-            // TODO No radio buttons in wxGTK yet
-#ifndef __WXGTK__
-            else if ( IsKindOf(CLASSINFO(wxRadioButton)) )
+#endif // wxUSE_CHECKBOX
+
+#if wxUSE_RADIOBUTTON
+            wxRadioButton *radiobtn = wxDynamicCast(this, wxRadioButton);
+            if ( radiobtn )
             {
                 if ( event.GetSetChecked() )
-                    ((wxRadioButton *) this)->SetValue(event.GetChecked());
+                    radiobtn->SetValue(event.GetChecked());
             }
-#endif // !wxGTK
+#endif // wxUSE_RADIOBUTTON
         }
     }
 }
@@ -1130,9 +1207,11 @@ wxPoint wxWindowBase::ConvertPixelsToDialog(const wxPoint& pt)
 {
     int charWidth = GetCharWidth();
     int charHeight = GetCharHeight();
-    wxPoint pt2;
-    pt2.x = (int) ((pt.x * 4) / charWidth) ;
-    pt2.y = (int) ((pt.y * 8) / charHeight) ;
+    wxPoint pt2(-1, -1);
+    if (pt.x != -1)
+        pt2.x = (int) ((pt.x * 4) / charWidth) ;
+    if (pt.y != -1)
+        pt2.y = (int) ((pt.y * 8) / charHeight) ;
 
     return pt2;
 }
@@ -1141,13 +1220,56 @@ wxPoint wxWindowBase::ConvertDialogToPixels(const wxPoint& pt)
 {
     int charWidth = GetCharWidth();
     int charHeight = GetCharHeight();
-    wxPoint pt2;
-    pt2.x = (int) ((pt.x * charWidth) / 4) ;
-    pt2.y = (int) ((pt.y * charHeight) / 8) ;
+    wxPoint pt2(-1, -1);
+    if (pt.x != -1)
+        pt2.x = (int) ((pt.x * charWidth) / 4) ;
+    if (pt.y != -1)
+        pt2.y = (int) ((pt.y * charHeight) / 8) ;
 
     return pt2;
 }
 
+// ----------------------------------------------------------------------------
+// client data
+// ----------------------------------------------------------------------------
+
+void wxWindowBase::DoSetClientObject( wxClientData *data )
+{
+    wxASSERT_MSG( m_clientDataType != ClientData_Void,
+                  wxT("can't have both object and void client data") );
+
+    if ( m_clientObject )
+        delete m_clientObject;
+
+    m_clientObject = data;
+    m_clientDataType = ClientData_Object;
+}
+
+wxClientData *wxWindowBase::DoGetClientObject() const
+{
+    wxASSERT_MSG( m_clientDataType == ClientData_Object,
+                  wxT("this window doesn't have object client data") );
+
+    return m_clientObject;
+}
+
+void wxWindowBase::DoSetClientData( void *data )
+{
+    wxASSERT_MSG( m_clientDataType != ClientData_Object,
+                  wxT("can't have both object and void client data") );
+
+    m_clientData = data;
+    m_clientDataType = ClientData_Void;
+}
+
+void *wxWindowBase::DoGetClientData() const
+{
+    wxASSERT_MSG( m_clientDataType == ClientData_Void,
+                  wxT("this window doesn't have void client data") );
+
+    return m_clientData;
+}
+
 // ----------------------------------------------------------------------------
 // event handlers
 // ----------------------------------------------------------------------------