]> git.saurik.com Git - wxWidgets.git/blobdiff - include/wx/propgrid/property.h
Test using wxString::ToCDouble() in wxAny.
[wxWidgets.git] / include / wx / propgrid / property.h
index f6373b517be5ecc360be6271d35cdbf6a757b621..f7364c14a06c7009f69957de20356f99b45e93d5 100644 (file)
@@ -6,12 +6,14 @@
 // Created:     2008-08-23
 // RCS-ID:      $Id$
 // Copyright:   (c) Jaakko Salli
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 #ifndef _WX_PROPGRID_PROPERTY_H_
 #define _WX_PROPGRID_PROPERTY_H_
 
+#include "wx/defs.h"
+
 #if wxUSE_PROPGRID
 
 #include "wx/propgrid/propgriddefs.h"
@@ -47,9 +49,6 @@ struct wxPGPaintData
 };
 
 
-#ifndef SWIG
-
-
 // space between vertical sides of a custom image
 #define wxPG_CUSTOM_IMAGE_SPACINGY      1
 
@@ -220,7 +219,6 @@ protected:
     bool        m_hasValidText;
 };
 
-#endif  // !SWIG
 
 /**
     @class wxPGCell
@@ -308,6 +306,13 @@ public:
         return *this;
     }
 
+    // Used mostly internally to figure out if this cell is supposed
+    // to have default values when attached to a grid.
+    bool IsInvalid() const
+    {
+        return ( m_refData == NULL );
+    }
+
 private:
     virtual wxObjectRefData *CreateRefData() const
         { return new wxPGCellData(); }
@@ -317,8 +322,6 @@ private:
 
 // -----------------------------------------------------------------------
 
-#ifndef SWIG
-
 /** @class wxPGAttributeStorage
 
     wxPGAttributeStorage is somewhat optimized storage for
@@ -366,7 +369,6 @@ protected:
     wxPGHashMapS2P  m_map;
 };
 
-#endif  // !SWIG
 
 // -----------------------------------------------------------------------
 
@@ -374,7 +376,7 @@ protected:
     @{
 */
 
-enum wxPG_PROPERTY_FLAGS
+enum wxPGPropertyFlags
 {
 
 /** Indicates bold font.
@@ -408,8 +410,8 @@ wxPG_PROP_COLLAPSED                 = 0x0020,
     If property is selected, then indicates that validation failed for pending
     value.
 
-    If property is not selected, then indicates that the the actual property
-    value has failed validation (NB: this behavior is not currently supported,
+    If property is not selected, that indicates that the actual property
+    value has failed validation (NB: this behaviour is not currently supported,
     but may be used in future).
 */
 wxPG_PROP_INVALID_VALUE             = 0x0040,
@@ -480,6 +482,8 @@ wxPG_PROP_USES_COMMON_VALUE         = 0x00020000,
 
     @remarks
     This flag cannot be used with property iterators.
+
+    @see wxPGProperty::SetAutoUnspecified()
 */
 wxPG_PROP_AUTO_UNSPECIFIED          = 0x00040000,
 
@@ -506,7 +510,9 @@ wxPG_PROP_BEING_DELETED             = 0x00200000
     Code should automatically take care of this, however.
 */
 #define wxPG_PROP_PARENTAL_FLAGS \
-    (wxPG_PROP_AGGREGATE|wxPG_PROP_CATEGORY|wxPG_PROP_MISC_PARENT)
+    ((wxPGPropertyFlags)(wxPG_PROP_AGGREGATE | \
+                         wxPG_PROP_CATEGORY | \
+                         wxPG_PROP_MISC_PARENT))
 
 /** @}
 */
@@ -517,8 +523,6 @@ wxPG_PROP_BEING_DELETED             = 0x00200000
 
 // -----------------------------------------------------------------------
 
-#ifndef SWIG
-
 /**
     @section propgrid_property_attributes wxPropertyGrid Property Attribute
     Identifiers.
@@ -646,11 +650,25 @@ wxPG_PROP_BEING_DELETED             = 0x00200000
 */
 #define wxPG_FILE_DIALOG_TITLE              wxS("DialogTitle")
 
+/** Specific to wxFileProperty and derivatives, long, default is 0.
+    Sets a specific wxFileDialog style for the file dialog.
+*/
+#define wxPG_FILE_DIALOG_STYLE              wxS("DialogStyle")
+
 /** Specific to wxDirProperty, wxString, default is empty.
     Sets a specific message for the dir dialog.
 */
 #define wxPG_DIR_DIALOG_MESSAGE             wxS("DialogMessage")
 
+/**
+    wxArrayStringProperty's string delimiter character. If this is a quotation
+    mark or hyphen, then strings will be quoted instead (with given
+    character).
+
+    Default delimiter is quotation mark.
+*/
+#define wxPG_ARRAY_DELIMITER                wxS("Delimiter")
+
 /** Sets displayed date format for wxDateProperty.
 */
 #define wxPG_DATE_FORMAT                    wxS("DateFormat")
@@ -661,7 +679,7 @@ wxPG_PROP_BEING_DELETED             = 0x00200000
 #define wxPG_DATE_PICKER_STYLE              wxS("PickerStyle")
 
 /** SpinCtrl editor, int or double. How much number changes when button is
-    pressed (or up/down on keybard).
+    pressed (or up/down on keyboard).
 */
 #define wxPG_ATTR_SPINCTRL_STEP             wxS("Step")
 
@@ -684,6 +702,12 @@ wxPG_PROP_BEING_DELETED             = 0x00200000
 */
 #define wxPG_COLOUR_ALLOW_CUSTOM            wxS("AllowCustom")
 
+/**
+    wxColourProperty and its kind: Set to True in order to support editing
+    alpha colour component.
+*/
+#define wxPG_COLOUR_HAS_ALPHA               wxS("HasAlpha")
+
 /** @}
 */
 
@@ -703,12 +727,8 @@ wxPG_PROP_BEING_DELETED             = 0x00200000
 #define wxPG_ATTR_INLINE_HELP             wxPGGlobalVars->m_strInlineHelp
 #endif
 
-#endif  // !SWIG
-
 // -----------------------------------------------------------------------
 
-#ifndef SWIG
-
 /** @class wxPGChoiceEntry
     Data of a single wxPGChoices choice.
 */
@@ -789,7 +809,6 @@ private:
 
 #define wxPGChoicesEmptyData    ((wxPGChoicesData*)NULL)
 
-#endif // SWIG
 
 /** @class wxPGChoices
 
@@ -952,7 +971,7 @@ public:
     }
 
     /** Gets a unsigned number identifying this list. */
-    wxPGChoicesId GetId() const { return (wxPGChoicesId) m_data; };
+    wxPGChoicesId GetId() const { return (wxPGChoicesId) m_data; }
 
     const wxString& GetLabel( unsigned int ind ) const
     {
@@ -1014,14 +1033,14 @@ public:
     /** Removes count items starting at position nIndex. */
     void RemoveAt(size_t nIndex, size_t count = 1);
 
-#ifndef SWIG
-    /** Does not create copies for itself. */
+    /** Does not create copies for itself.
+        TODO: Deprecate.
+    */
     void Set( const wxChar* const* labels, const long* values = NULL )
     {
         Free();
         Add(labels,values);
     }
-#endif // SWIG
 
     /** Version that works with wxArrayString and wxArrayInt. */
     void Set( const wxArrayString& labels,
@@ -1058,7 +1077,6 @@ public:
 
     wxArrayString GetLabels() const;
 
-#ifndef SWIG
     void operator= (const wxPGChoices& a)
     {
         if (this != &a)
@@ -1080,7 +1098,6 @@ protected:
 
     void Init();
     void Free();
-#endif  // !SWIG
 };
 
 // -----------------------------------------------------------------------
@@ -1143,7 +1160,6 @@ public:
     */
     virtual wxVariant DoGetValue() const { return m_value; }
 
-#if !defined(SWIG) || defined(CREATE_VCW)
     /** Implement this function in derived class to check the value.
         Return true if it is ok. Returning false prevents property change events
         from occurring.
@@ -1178,7 +1194,7 @@ public:
 
                 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).
+                you explicitly enabled that sort behaviour).
     */
     virtual bool StringToValue( wxVariant& variant,
                                 const wxString& text,
@@ -1210,12 +1226,12 @@ public:
           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).
+          explicitly enabled that sort behaviour).
     */
     virtual bool IntToValue( wxVariant& value,
                              int number,
                              int argFlags = 0 ) const;
-#endif  // !defined(SWIG) || defined(CREATE_VCW)
+
     /**
         Converts property value into a text representation.
 
@@ -1236,7 +1252,7 @@ public:
     virtual wxString ValueToString( wxVariant& value, int argFlags = 0 ) const;
 
     /** Converts string to a value, and if successful, calls SetValue() on it.
-        Default behavior is to do nothing.
+        Default behaviour is to do nothing.
         @param text
         String to get the value from.
         @return
@@ -1244,8 +1260,8 @@ public:
     */
     bool SetValueFromString( const wxString& text, int flags = wxPG_PROGRAMMATIC_VALUE );
 
-    /** Converts integer to a value, and if succesful, calls SetValue() on it.
-        Default behavior is to do nothing.
+    /** Converts integer to a value, and if successful, calls SetValue() on it.
+        Default behaviour is to do nothing.
         @param value
             Int to get the value from.
         @param flags
@@ -1264,7 +1280,7 @@ public:
         @param item
             Normally -1, but can be an index to the property's list of items.
         @remarks
-        - Default behavior is to return wxSize(0,0), which means no image.
+        - Default behaviour is to return wxSize(0,0), which means no image.
         - Default image width or height is indicated with dimension -1.
         - You can also return wxPG_DEFAULT_IMAGE_SIZE, i.e. wxSize(-1, -1).
     */
@@ -1277,7 +1293,7 @@ public:
         button press events of TextCtrlAndButton class, can be handled here.
         Also, if custom handling for regular events is desired, then that can
         also be done (for example, wxSystemColourProperty custom handles
-        wxEVT_COMMAND_CHOICE_SELECTED to display colour picker dialog when
+        wxEVT_CHOICE to display colour picker dialog when
         'custom' selection is made).
 
         If the event causes value to be changed, SetValueInEvent()
@@ -1298,7 +1314,7 @@ public:
 
     /**
         Called after value of a child property has been altered. Must return
-        new value of the whole property (after any alterations warrented by
+        new value of the whole property (after any alterations warranted by
         child's new value).
 
         Note that this function is usually called at the time that value of
@@ -1529,6 +1545,17 @@ public:
     */
     void DeleteChoice( int index );
 
+    /**
+        Enables or disables the property. Disabled property usually appears
+        as having grey text.
+
+        @param enable
+            If @false, property is disabled instead.
+
+        @see wxPropertyGridInterface::EnableProperty()
+    */
+    void Enable( bool enable = true );
+
     /**
         Call to enable or disable usage of common value (integer value that can
         be selected for properties instead of their normal values) for this
@@ -1685,7 +1712,7 @@ public:
     /** Returns true if property has editable wxTextCtrl when selected.
 
         @remarks
-        Altough disabled properties do not displayed editor, they still
+        Although disabled properties do not displayed editor, they still
         return True here as being disabled is considered a temporary
         condition (unlike being read-only or having limited editing enabled).
     */
@@ -1696,7 +1723,12 @@ public:
         return m_value.IsNull();
     }
 
-    FlagType HasFlag( FlagType flag ) const
+    /**
+        Returns non-zero if property has given flag set.
+
+        @see propgrid_propflags
+    */
+    FlagType HasFlag( wxPGPropertyFlags flag ) const
     {
         return ( m_flags & flag );
     }
@@ -1712,6 +1744,9 @@ public:
     */
     wxVariant GetAttributesAsList() const;
 
+    /**
+        Returns property flags.
+    */
     FlagType GetFlags() const
     {
         return m_flags;
@@ -1865,7 +1900,7 @@ public:
             By default changes are applied recursively. Set this paramter
             wxPG_DONT_RECURSE to prevent this.
     */
-    inline bool Hide( bool hide, int flags = wxPG_RECURSE );
+    bool Hide( bool hide, int flags = wxPG_RECURSE );
 
     bool IsExpanded() const
         { return (!(m_flags & wxPG_PROP_COLLAPSED) && GetChildCount()); }
@@ -1895,6 +1930,21 @@ public:
 
     void SetAttributes( const wxPGAttributeStorage& attributes );
 
+    /**
+        Set if user can change the property's value to unspecified by
+        modifying the value of the editor control (usually by clearing
+        it).  Currently, this can work with following properties:
+        wxIntProperty, wxUIntProperty, wxFloatProperty, wxEditEnumProperty.
+
+        @param enable
+            Whether to enable or disable this behaviour (it is disabled by
+            default).
+    */
+    void SetAutoUnspecified( bool enable = true )
+    {
+        ChangeFlag(wxPG_PROP_AUTO_UNSPECIFIED, enable);
+    }
+
     /**
         Sets property's background colour.
 
@@ -1931,7 +1981,6 @@ public:
     */
     void SetDefaultValue( wxVariant& value );
 
-#ifndef SWIG
     /** Sets editor for a property.
 
         @param editor
@@ -1946,7 +1995,6 @@ public:
     {
         m_customEditor = editor;
     }
-#endif
 
     /** Sets editor for a property.
     */
@@ -2028,14 +2076,16 @@ public:
     }
 
     /**
-        Sets given property flag(s).
-    */
-    void SetFlag( FlagType flag ) { m_flags |= flag; }
+        Sets or clears given property flag. Mainly for internal use.
 
-    /**
-        Sets or clears given property flag(s).
+        @remarks Setting a property flag never has any side-effect, and is
+                 intended almost exclusively for internal use. So, for
+                 example, if you want to disable a property, call
+                 Enable(false) instead of setting wxPG_PROP_DISABLED flag.
+
+        @see HasFlag(), GetFlags()
     */
-    void ChangeFlag( FlagType flag, bool set )
+    void ChangeFlag( wxPGPropertyFlags flag, bool set )
     {
         if ( set )
             m_flags |= flag;
@@ -2043,7 +2093,13 @@ public:
             m_flags &= ~flag;
     }
 
-    void SetFlagRecursively( FlagType flag, bool set );
+    /**
+        Sets or clears given property flag, recursively. This function is
+        primarily intended for internal use.
+
+        @see ChangeFlag()
+    */
+    void SetFlagRecursively( wxPGPropertyFlags flag, bool set );
 
     void SetHelpString( const wxString& helpString )
     {
@@ -2100,7 +2156,6 @@ public:
     }
 #endif // wxUSE_VALIDATORS
 
-#ifndef SWIG
     /** Returns client data (void*) of a property.
     */
     void* GetClientData() const
@@ -2128,14 +2183,14 @@ public:
     /** Sets managed client object of a property.
     */
     wxClientData *GetClientObject() const { return m_clientObject; }
-#endif
 
-    /** Sets new set of choices for property.
+    /**
+        Sets new set of choices for the property.
 
-        @remarks
-        This operation clears the property value.
+        @remarks This operation deselects the property and clears its
+                 value.
     */
-    bool SetChoices( wxPGChoices& choices );
+    bool SetChoices( const wxPGChoices& choices );
 
     /** Set max length of text in text editor.
     */
@@ -2155,8 +2210,6 @@ public:
         return m_helpString;
     }
 
-    void ClearFlag( FlagType flag ) { m_flags &= ~(flag); }
-
     // Use, for example, to detect if item is inside collapsed section.
     bool IsSomeParent( wxPGProperty* candidate_parent ) const;
 
@@ -2226,16 +2279,12 @@ public:
     */
     int GetImageOffset( int imageWidth ) const;
 
-#ifndef SWIG
     // Returns wxPropertyGridPageState in which this property resides.
     wxPropertyGridPageState* GetParentState() const { return m_parentState; }
-#endif
 
-#ifndef SWIG
     wxPGProperty* GetItemAtY( unsigned int y,
                               unsigned int lh,
                               unsigned int* nextItemY ) const;
-#endif
 
     /** Returns property at given virtual y coordinate.
     */
@@ -2245,8 +2294,6 @@ public:
     */
     wxPGProperty* GetPropertyByName( const wxString& name ) const;
 
-#ifndef SWIG
-
     // Returns various display-related information for given column
     void GetDisplayInfo( unsigned int column,
                          int choiceIndex,
@@ -2328,6 +2375,8 @@ protected:
                                   const wxVariantList* valueOverrides = NULL,
                                   wxPGHashMapS2S* childResults = NULL ) const;
 
+    bool DoHide( bool hide, int flags );
+
     void DoSetName(const wxString& str) { m_name = str; }
 
     /** Deletes all sub-properties. */
@@ -2343,14 +2392,37 @@ protected:
     void InitAfterAdded( wxPropertyGridPageState* pageState,
                          wxPropertyGrid* propgrid );
 
+    /**
+        Returns true if child property is selected.
+    */
+    bool IsChildSelected( bool recursive = false ) const;
+
     // Removes child property with given pointer. Does not delete it.
     void RemoveChild( wxPGProperty* p );
 
+    void DoEnable( bool enable );
+
     void DoPreAddChild( int index, wxPGProperty* prop );
 
     void SetParentState( wxPropertyGridPageState* pstate )
         { m_parentState = pstate; }
 
+    void SetFlag( wxPGPropertyFlags flag )
+    {
+        //
+        // NB: While using wxPGPropertyFlags here makes it difficult to
+        //     combine different flags, it usefully prevents user from
+        //     using incorrect flags (say, wxWindow styles).
+        m_flags |= flag;
+    }
+
+    void ClearFlag( FlagType flag ) { m_flags &= ~(flag); }
+
+    // Called when the property is being removed from the grid and/or
+    // page state (but *not* when it is also deleted).
+    void OnDetached(wxPropertyGridPageState* state,
+                    wxPropertyGrid* propgrid);
+
     // Call after fixed sub-properties added/removed after creation.
     // if oldSelInd >= 0 and < new max items, then selection is
     // moved to it.
@@ -2414,7 +2486,6 @@ private:
     // Called in constructors.
     void Init();
     void Init( const wxString& label, const wxString& name );
-#endif // #ifndef SWIG
 };
 
 // -----------------------------------------------------------------------
@@ -2427,14 +2498,12 @@ private:
 #define WX_PG_DECLARE_DOGETEDITORCLASS \
     virtual const wxPGEditor* DoGetEditorClass() const;
 
-#ifndef SWIG
+#ifndef WX_PG_DECLARE_PROPERTY_CLASS
     #define WX_PG_DECLARE_PROPERTY_CLASS(CLASSNAME) \
         public: \
             DECLARE_DYNAMIC_CLASS(CLASSNAME) \
             WX_PG_DECLARE_DOGETEDITORCLASS \
         private:
-#else
-    #define WX_PG_DECLARE_PROPERTY_CLASS(CLASSNAME)
 #endif
 
 // Implements sans constructor function. Also, first arg is class name, not
@@ -2447,8 +2516,6 @@ const wxPGEditor* PROPNAME::DoGetEditorClass() const \
 
 // -----------------------------------------------------------------------
 
-#ifndef SWIG
-
 /** @class wxPGRootProperty
     @ingroup classes
     Root parent property.
@@ -2511,8 +2578,6 @@ private:
     void Init();
 };
 
-#endif  // !SWIG
-
 // -----------------------------------------------------------------------
 
 #endif // wxUSE_PROPGRID