Replaced 'InlineHelp' property attribute with 'Hint'; Use SetHint() wxTextCtrl and wxComboCtrl member function to set it; Added a small section about help string and hint text in propgrid overview

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@62990 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/doxygen/overviews/propgrid.h

@@ -35,6 +35,7 @@ should carefully read final section in @ref propgrid_compat.
 @li @ref propgrid_processingvalues
 @li @ref propgrid_iterating
 @li @ref propgrid_events
+@li @ref propgrid_tooltipandhint
 @li @ref propgrid_validating
 @li @ref propgrid_populating
 @li @ref propgrid_cellrender
@@ -637,6 +638,19 @@ void MyForm::OnPropertyGridChanging( wxPropertyGridEvent& event )
   to obtain its topmost non-category parent (useful, if you have deeply nested
   properties).
 
+@section propgrid_tooltipandhint Help String, Hint and Tool Tips
+
+For each property you can specify two different types of help text. First,
+you can use wxPropertyGridInterface::SetPropertyHelpString() or
+wxPGProperty::SetHelpString() to set property's help text. Second, you
+can use wxPGProperty::SetAttribute() to set property's "Hint" attribute.
+
+Difference between hint and help string is that the hint is shown in an empty
+property value cell, while help string is shown either in the description text
+box, as a tool tip, or on the status bar, whichever of these is available.
+
+To enable display of help string as tool tips, you must explicitly use
+the wxPG_EX_HELP_AS_TOOLTIPS extra window style.
 
 @section propgrid_validating Validating Property Values
 
@@ -946,6 +960,8 @@ without warnings or errors.
   - wxPropertyGridEvent::HasProperty() is removed. You can use GetProperty()
     as immediate replacement when checking if event has a property.
 
+  - "InlineHelp" property has been replaced with "Hint".
+
 @subsection propgrid_compat_propdev Property and Editor Sub-classing Changes
 
   - Confusing custom property macros have been eliminated.

include/wx/propgrid/property.h

@@ -546,10 +546,17 @@ wxPG_PROP_BEING_DELETED             = 0x00200000
 */
 #define wxPG_ATTR_UNITS                     wxS("Units")
 
-/** Universal, string. When set, will be shown in property's value cell
-    when displayed value string is empty, or value is unspecified.
+/** When set, will be shown as 'greyed' text in property's value cell when
+    the actual displayed value is blank.
+*/
+#define wxPG_ATTR_HINT                      wxS("Hint")
+
+#if wxPG_COMPATIBILITY_1_4
+/**
+    @deprecated Use "Hint" (wxPG_ATTR_INLINE_HELP) instead.
 */
 #define wxPG_ATTR_INLINE_HELP               wxS("InlineHelp")
+#endif
 
 /** Universal, wxArrayString. Set to enable auto-completion in any
     wxTextCtrl-based property editor.
@@ -683,8 +690,12 @@ wxPG_PROP_BEING_DELETED             = 0x00200000
 #define wxPG_ATTR_MAX                     wxPGGlobalVars->m_strMax
 #undef wxPG_ATTR_UNITS
 #define wxPG_ATTR_UNITS                   wxPGGlobalVars->m_strUnits
+#undef wxPG_ATTR_HINT
+#define wxPG_ATTR_HINT                    wxPGGlobalVars->m_strHint
+#if wxPG_COMPATIBILITY_1_4
 #undef wxPG_ATTR_INLINE_HELP
 #define wxPG_ATTR_INLINE_HELP             wxPGGlobalVars->m_strInlineHelp
+#endif
 
 #endif  // !SWIG
 
@@ -1638,6 +1649,11 @@ public:
         return GetValueAsString(0);
     }
 
+    /**
+        Returns property's hint text (shown in empty value cell).
+    */
+    inline wxString GetHintText() const;
+
     /** Returns property grid where property lies. */
     wxPropertyGrid* GetGrid() const;
 

include/wx/propgrid/propgrid.h

@@ -87,7 +87,10 @@ public:
     wxPGCachedString    m_strMin;
     wxPGCachedString    m_strMax;
     wxPGCachedString    m_strUnits;
+    wxPGCachedString    m_strHint;
+#if wxPG_COMPATIBILITY_1_4
     wxPGCachedString    m_strInlineHelp;
+#endif
 
     // If true then some things are automatically translated
     bool                m_autoGetTranslation;
@@ -2146,6 +2149,22 @@ inline unsigned int wxPropertyGridPageState::GetActualVirtualHeight() const
 }
 #endif
 
+wxString wxPGProperty::GetHintText() const
+{
+    wxVariant vHintText = GetAttribute(wxPGGlobalVars->m_strHint);
+
+#if wxPG_COMPATIBILITY_1_4
+    // Try the old, deprecated "InlineHelp"
+    if ( vHintText.IsNull() )
+        vHintText = GetAttribute(wxPGGlobalVars->m_strInlineHelp);
+#endif
+
+    if ( !vHintText.IsNull() )
+        return vHintText.GetString();
+
+    return wxEmptyString;
+}
+
 inline int wxPGProperty::GetDisplayedCommonValueCount() const
 {
     if ( HasFlag(wxPG_PROP_USES_COMMON_VALUE) )

interface/wx/propgrid/property.h

@@ -41,8 +41,13 @@
 */
 #define wxPG_ATTR_UNITS                     wxS("Units")
 
-/** Universal, string. When set, will be shown in property's value cell
-    when displayed value string is empty, or value is unspecified.
+/** When set, will be shown as 'greyed' text in property's value cell when
+    the actual displayed value is blank.
+*/
+#define wxPG_ATTR_HINT                      wxS("Hint")
+
+/**
+    @deprecated Use "Hint" (wxPG_ATTR_INLINE_HELP) instead.
 */
 #define wxPG_ATTR_INLINE_HELP               wxS("InlineHelp")
 

samples/propgrid/propgrid.cpp

@@ -1319,10 +1319,16 @@ void FormMain::PopulateWithStandardItems ()
     pg->SetPropertyAttribute(wxT("Height"), wxPG_ATTR_MAX, (long)2048 );
     pg->SetPropertyAttribute(wxT("Height"), wxPG_ATTR_UNITS, wxT("Pixels") );
 
-    // Set value to unspecified so that InlineHelp attribute will be demonstrated
-    pg->SetPropertyValueUnspecified(wxT("Height"));
-    pg->SetPropertyAttribute(wxT("Height"), wxPG_ATTR_INLINE_HELP, wxT("Enter new height for window") );
-    pg->SetPropertyHelpString(wxT("Height"), wxT("This property uses attributes \"Units\" and \"InlineHelp\".") );
+    // Set value to unspecified so that Hint attribute will be demonstrated
+    pg->SetPropertyValueUnspecified("Height");
+    pg->SetPropertyAttribute("Height", wxPG_ATTR_HINT,
+                             "Enter new height for window" );
+
+    // Difference between hint and help string is that the hint is shown in
+    // an empty value cell, while help string is shown either in the
+    // description text box, as a tool tip, or on the status bar.
+    pg->SetPropertyHelpString("Height",
+        "This property uses attributes \"Units\" and \"InlineHelp\"." );
 
     pg->Append( new wxIntProperty(wxT("Width"),wxPG_LABEL,640) );
     pg->SetPropertyAttribute(wxT("Width"), wxPG_ATTR_MIN, (long)10 );
@@ -1547,6 +1553,7 @@ void FormMain::PopulateWithExamples ()
     soc.Add( wxT("Look, it continues"), 200 );
     soc.Add( wxT("Even More"), 240 );
     soc.Add( wxT("And More"), 280 );
+    soc.Add( "", 300 );
     soc.Add( wxT("True End of the List"), 320 );
 
     // Test custom colours ([] operator of wxPGChoices returns
@@ -1569,6 +1576,12 @@ void FormMain::PopulateWithExamples ()
     pg->Append( new wxEnumProperty(wxT("EnumProperty 3"),wxPG_LABEL,
         soc, 240 ) );
 
+    // Test Hint attribute in EnumProperty
+    pg->GetProperty("EnumProperty 3")->SetAttribute("Hint", "Dummy Hint");
+
+    pg->SetPropertyHelpString("EnumProperty 3",
+        "This property uses \"Hint\" attribute.");
+
     // 'soc' plus one exclusive extra choice "4th only"
     pg->Append( new wxEnumProperty(wxT("EnumProperty 4"),wxPG_LABEL,
         soc, 240 ) );
@@ -1680,6 +1693,9 @@ void FormMain::PopulateWithExamples ()
                                        eech,
                                        "Choice not in the list") );
 
+    // Test Hint attribute in EditEnumProperty
+    pg->GetProperty("EditEnumProperty")->SetAttribute("Hint", "Dummy Hint");
+
     //wxString v_;
     //wxTextValidator validator1(wxFILTER_NUMERIC,&v_);
     //pg->SetPropertyValidator( wxT("EditEnumProperty"), validator1 );

src/propgrid/editors.cpp

@@ -482,7 +482,7 @@ void wxPGTextCtrlEditor_OnFocus( wxPGProperty* property,
                                  wxTextCtrl* tc )
 {
     // Make sure there is correct text (instead of unspecified value
-    // indicator or inline help)
+    // indicator or hint text)
     int flags = property->HasFlag(wxPG_PROP_READONLY) ? 
         0 : wxPG_EDITABLE_VALUE;
     wxString correctText = property->GetValueAsString(flags);
@@ -656,7 +656,17 @@ public:
                              int flags ) const
     {
         wxPropertyGrid* pg = GetGrid();
-        pg->OnComboItemPaint( this, item, &dc, (wxRect&)rect, flags );
+
+        // Handle hint text via super class
+        if ( (flags & wxODCB_PAINTING_CONTROL) &&
+             ShouldUseHintText(flags) )
+        {
+            wxOwnerDrawnComboBox::OnDrawItem(dc, rect, item, flags);
+        }
+        else
+        {
+            pg->OnComboItemPaint( this, item, &dc, (wxRect&)rect, flags );
+        }
     }
 
     virtual wxCoord OnMeasureItem( size_t item ) const
@@ -1032,7 +1042,11 @@ wxWindow* wxPGChoiceEditor::CreateControlsBase( wxPropertyGrid* propGrid,
     cb->SetButtonPosition(si.y,0,wxRIGHT);
     cb->SetMargins(wxPG_XBEFORETEXT-1);
 
-    wxPGChoiceEditor_SetCustomPaintWidth( propGrid, cb, property->GetCommonValue() );
+    // Set hint text
+    cb->SetHint(property->GetHintText());
+
+    wxPGChoiceEditor_SetCustomPaintWidth( propGrid, cb,
+                                          property->GetCommonValue() );
 
     if ( index >= 0 && index < (int)cb->GetCount() )
     {
@@ -1898,6 +1912,9 @@ wxWindow* wxPropertyGrid::GenerateEditorTextCtrl( const wxPoint& pos,
         tc->AutoComplete(attrVal.GetArrayString());
     }
 
+    // Set hint text
+    tc->SetHint(prop->GetHintText());
+
     return tc;
 }
 

src/propgrid/property.cpp

@@ -259,12 +259,12 @@ void wxPGDefaultRenderer::Render( wxDC& dc, const wxRect& rect,
 
         if ( text.length() == 0 )
         {
-            // Try to show inline help if no text
-            wxVariant vInlineHelp = property->GetAttribute(wxPGGlobalVars->m_strInlineHelp);
-            if ( !vInlineHelp.IsNull() )
+            text = property->GetHintText();
+            if ( text.length() > 0 )
             {
-                text = vInlineHelp.GetString();
-                dc.SetTextForeground(propertyGrid->GetCellDisabledTextColour());
+                const wxColour& hCol =
+                    propertyGrid->GetCellDisabledTextColour();
+                dc.SetTextForeground(hCol);
 
                 // Must make the editor NULL to override it's own rendering
                 // code.

src/propgrid/propgrid.cpp

@@ -200,7 +200,10 @@ wxPGGlobalVarsClass::wxPGGlobalVarsClass()
     m_strMin = wxS("Min");
     m_strMax = wxS("Max");
     m_strUnits = wxS("Units");
+    m_strHint = wxS("Hint");
+#if wxPG_COMPATIBILITY_1_4
     m_strInlineHelp = wxS("InlineHelp");
+#endif
 
     m_warnings = 0;
 }