fix PCH in VC8 projects (until the next rebake...)

[wxWidgets.git] / interface / wx / propgrid / property.h

diff --git a/interface/wx/propgrid/property.h b/interface/wx/propgrid/property.h
index 83947621270f221247af81b425b89494b964861a..057154a0a62e759b37260cd701bb7663b7065c00 100644 (file)
--- a/interface/wx/propgrid/property.h
+++ b/interface/wx/propgrid/property.h
@@ -2,7 +2,7 @@
 // Name:        property.h
 // Purpose:     interface of wxPGProperty
 // Author:      wxWidgets team
 // Name:        property.h
 // Purpose:     interface of wxPGProperty
 // Author:      wxWidgets team

-// RCS-ID:      $Id:
+// RCS-ID:      $Id$

 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 


@@ -234,6 +234,37 @@
     dialog. Note that in long string values, tabs are represented by "\t" and
     line break by "\n".
 
     dialog. Note that in long string values, tabs are represented by "\t" and
     line break by "\n".
 

+    To display custom dialog on button press, you can subclass
+    wxLongStringProperty and implement OnButtonClick, like this:
+
+    @code
+        virtual bool OnButtonClick( wxPropertyGrid* propGrid, wxString& value )
+        {
+            wxSize dialogSize(...size of your dialog...);
+
+            wxPoint dlgPos = propGrid->GetGoodEditorDialogPosition(this,
+                                                                   dialogSize)
+
+            // Create dialog dlg at dlgPos. Use value as initial string
+            // value.
+            ...
+
+            if ( dlg.ShowModal() == wxID_OK )
+            {
+                value = dlg.GetStringValue);
+                return true;
+            }
+            return false;
+        }
+    @endcode
+
+    Also, if you wish not to have line breaks and tabs translated to
+    escape sequences, then do following in constructor of your subclass:
+
+    @code
+        m_flags |= wxPG_PROP_NO_ESCAPE;
+    @endcode
+

     @subsection wxDirProperty
 
     Like wxLongStringProperty, but the button triggers dir selector instead.
     @subsection wxDirProperty
 
     Like wxLongStringProperty, but the button triggers dir selector instead.


@@ -295,6 +326,8 @@
     <b>Useful alternate editor:</b> Choice.
 
     Represents wxColour. wxButton is used to trigger a colour picker dialog.
     <b>Useful alternate editor:</b> Choice.
 
     Represents wxColour. wxButton is used to trigger a colour picker dialog.

+    There are various sub-classing opportunities with this class. See
+    below in wxSystemColourProperty section for details.

 
     @subsection wxFontProperty
 
 
     @subsection wxFontProperty
 


@@ -305,7 +338,9 @@
 
     Represents wxColour and a system colour index. wxChoice is used to edit
     the value. Drop-down list has color images. Note that value type
 
     Represents wxColour and a system colour index. wxChoice is used to edit
     the value. Drop-down list has color images. Note that value type

-    is wxColourPropertyValue instead of wxColour.
+    is wxColourPropertyValue instead of wxColour (which wxColourProperty
+    uses).
+

     @code
         class wxColourPropertyValue : public wxObject
         {
     @code
         class wxColourPropertyValue : public wxObject
         {


@@ -322,6 +357,27 @@
             wxColour    m_colour;
         };
     @endcode
             wxColour    m_colour;
         };
     @endcode

+    
+    in wxSystemColourProperty, and its derived class wxColourProperty, there
+    are various sub-classing features. To set basic list list of colour
+    names, call wxPGProperty::SetChoices().
+
+    @code
+        // Override in derived class to customize how colours are translated
+        // to strings.
+        virtual wxString ColourToString( const wxColour& col, int index ) const;
+
+        // Returns index of entry that triggers colour picker dialog
+        // (default is last).
+        virtual int GetCustomColourIndex() const;
+
+        // Helper function to show the colour dialog
+        bool QueryColourFromUser( wxVariant& variant ) const;
+
+        // Returns colour for given choice.
+        // Default function returns wxSystemSettings::GetColour(index).
+        virtual wxColour GetColour( int index ) const;
+    @endcode

 
     @subsection wxCursorProperty
 
 
     @subsection wxCursorProperty
 


@@ -473,33 +529,60 @@ public:
     virtual bool ValidateValue( wxVariant& value, wxPGValidationInfo& validationInfo ) const;
 
     /**
     virtual bool ValidateValue( wxVariant& value, wxPGValidationInfo& validationInfo ) const;
 
     /**

-        Converts 'text' into proper value 'variant'. Returns true if new (different than
-        m_value) value could be interpreted from the text.
+        Converts text into wxVariant value appropriate for this property.
+
+        @param variant
+            On function entry this is the old value (should not be wxNullVariant
+            in normal cases). Translated value must be assigned back to it.
+
+        @param text
+            Text to be translated into variant.
+

         @param argFlags
         @param argFlags

-        If wxPG_FULL_VALUE is set, returns complete, storable value instead of displayable
-        one (they may be different).
-        If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of composite
-        property string value (as generated by GetValueAsString() called with this same
-        flag).
+            If wxPG_FULL_VALUE is set, returns complete, storable value instead
+            of displayable one (they may be different).
+            If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of
+            composite property string value (as generated by GetValueAsString()
+            called with this same flag).

 
 

-        @remarks
-        Default implementation converts semicolon delimited tokens into child values. Only
-        works for properties with children.
+        @return Returns @true if resulting wxVariant value was different.
+
+        @remarks Default implementation converts semicolon delimited tokens into
+                child values. Only works for properties with children.
+
+                You might want to take into account that m_value is Null variant
+                if property value is unspecified (which is usually only case if
+                you explicitly enabled that sort behavior).

     */
     virtual bool StringToValue( wxVariant& variant, const wxString& text, int argFlags = 0 ) const;
 
     /**
     */
     virtual bool StringToValue( wxVariant& variant, const wxString& text, int argFlags = 0 ) const;
 
     /**

-        Converts 'number' (including choice selection) into proper value 'variant'.
-        Returns true if new (different than m_value) value could be interpreted from the integer.
+        Converts integer (possibly a choice selection) into wxVariant value
+        appropriate for this property.
+
+        @param variant
+            On function entry this is the old value (should not be wxNullVariant
+            in normal cases). Translated value must be assigned back to it.
+
+        @param number
+            Integer to be translated into variant.
+

         @param argFlags
         @param argFlags

-        If wxPG_FULL_VALUE is set, returns complete, storable value instead of displayable one.
+            If wxPG_FULL_VALUE is set, returns complete, storable value instead
+            of displayable one.
+
+        @return Returns @true if resulting wxVariant value was different.

 
         @remarks
         - If property is not supposed to use choice or spinctrl or other editor
           with int-based value, it is not necessary to implement this method.
         - Default implementation simply assign given int to m_value.
 
         @remarks
         - If property is not supposed to use choice or spinctrl or other editor
           with int-based value, it is not necessary to implement this method.
         - Default implementation simply assign given int to m_value.

-        - If property uses choice control, and displays a dialog on some choice items,
-          then it is preferred to display that dialog in IntToValue instead of OnEvent.
+        - If property uses choice control, and displays a dialog on some choice
+          items, then it is preferred to display that dialog in IntToValue
+          instead of OnEvent.
+        - You might want to take into account that m_value is Null variant if
+          property value is unspecified (which is usually only case if you
+          explicitly enabled that sort behavior).

     */
     virtual bool IntToValue( wxVariant& value, int number, int argFlags = 0 ) const;
 
     */
     virtual bool IntToValue( wxVariant& value, int number, int argFlags = 0 ) const;
 


@@ -785,8 +868,21 @@ public:
     int AddChoice( const wxString& label, int value = wxPG_INVALID_VALUE );
 
     /**
     int AddChoice( const wxString& label, int value = wxPG_INVALID_VALUE );
 
     /**

-        Properties which have private child properties should add them
-        with this function, called in their constructor.
+        Adds a child property. If you use this instead of
+        wxPropertyGridInterface::Insert() or
+        wxPropertyGridInterface::AppendIn(), then you must set up
+        property's parental type before making the call. To do this,
+        call property's SetParentalType() function with either
+        wxPG_PROP_MISC_PARENT (normal, public children) or with
+        wxPG_PROP_AGGREGATE (private children for subclassed property).
+        For instance:
+
+        @code
+            wxPGProperty* prop = new wxStringProperty(wxS("Property"));
+            prop->SetParentalType(wxPG_PROP_MISC_PARENT);
+            wxPGProperty* prop2 = new wxStringProperty(wxS("Property2"));
+            prop->AddChild(prop2);
+        @endcode

     */
     void AddChild( wxPGProperty* property );
 
     */
     void AddChild( wxPGProperty* property );
 


@@ -961,7 +1057,7 @@ public:
 
     /**
         Returns highest level non-category, non-root parent. Useful when you
 
     /**
         Returns highest level non-category, non-root parent. Useful when you

-        have nested wxCustomProperties/wxParentProperties.
+        have nested properties with children.

 
         @remarks If immediate parent is root or category, this will return the
                 property itself.
 
         @remarks If immediate parent is root or category, this will return the
                 property itself.


@@ -1111,25 +1207,7 @@ public:
     /**
         Returns child property at index i.
     */
     /**
         Returns child property at index i.
     */

-    wxPGProperty* Item( size_t i ) const;
-
-    /**
-        Updates property value in case there were last minute
-        changes. If value was unspecified, it will be set to default.
-        Use only for properties that have TextCtrl-based editor.
-
-        @remarks If you have code similar to
-                @code
-                // Update the value in case of last minute changes
-                if ( primary && propgrid->IsEditorsValueModified() )
-                     GetEditorClass()->CopyValueFromControl( this, primary );
-                @endcode
-                in wxPGProperty::OnEvent wxEVT_COMMAND_BUTTON_CLICKED handler,
-                then replace it with call to this method.
-
-        @return Returns @true if value changed.
-    */
-    bool PrepareValueForDialogEditing( wxPropertyGrid* propgrid );
+    wxPGProperty* Item( unsigned int i ) const;

 
     /**
         If property's editor is active, then update it's value.
 
     /**
         If property's editor is active, then update it's value.


@@ -1144,6 +1222,9 @@ public:
 
         @param value
             Value of attribute.
 
         @param value
             Value of attribute.

+
+        @remarks Setting attribute's value to Null variant will simply remove it
+                from property's set of attributes.

     */
     void SetAttribute( const wxString& name, wxVariant value );
 
     */
     void SetAttribute( const wxString& name, wxVariant value );
 


@@ -1231,6 +1312,23 @@ public:
     */
     void SetName( const wxString& newName );
 
     */
     void SetName( const wxString& newName );
 

+    /**
+        Changes what sort of parent this property is for its children.
+
+        @param flag
+            Use one of the following values: wxPG_PROP_MISC_PARENT (for generic
+            parents), wxPG_PROP_CATEGORY (for categories), or
+            wxPG_PROP_AGGREGATE (for derived property classes with private
+            children).
+
+        @remarks You only need to call this if you use AddChild() to add
+                 child properties. Adding properties with
+                 wxPropertyGridInterface::Insert() or
+                 wxPropertyGridInterface::AppendIn() will automatically set
+                 property to use wxPG_PROP_MISC_PARENT style.
+    */
+    void SetParentalType( int flag );
+

     /** Sets wxValidator for a property */
     void SetValidator( const wxValidator& validator );
 
     /** Sets wxValidator for a property */
     void SetValidator( const wxValidator& validator );
 


@@ -1380,17 +1478,17 @@ public:
     /**
         Returns labe of item.
     */
     /**
         Returns labe of item.
     */

-    const wxString& GetLabel( size_t ind ) const;
+    const wxString& GetLabel( unsigned int ind ) const;

 
     /**
         Returns number of items.
     */
 
     /**
         Returns number of items.
     */

-    size_t GetCount () const;
+    unsigned int GetCount() const;

 
     /**
         Returns value of item;
     */
 
     /**
         Returns value of item;
     */

-    int GetValue( size_t ind ) const;
+    int GetValue( unsigned int ind ) const;

 
     /**
         Returns array of values matching the given strings. Unmatching strings
 
     /**
         Returns array of values matching the given strings. Unmatching strings