propgrid.h

非常好用的可移植的多平台C/C++源代码编辑器

    wxPGConstants** m_constants;
    int             m_itemCount;
};


/** \class wxPGProperty
	\ingroup classes
    \brief wxPGProperty is base class for properties. Information here is
    provided primarily for anyone who creates new properties, since <b>all operations
    on properties should be done via wxPropertyGrid's or wxPropertyGridManager's
    methods</b>.

    \remarks
    - When changing name of a property, it is essential to use wxPropertyGrid::SetPropertyName
      (that's why there is no SetName method).
*/

#if wxPG_EMBED_VARIANT
class WXDLLIMPEXP_PG wxPGProperty : public wxVariant
#elif wxPG_INCLUDE_WXOBJECT
class WXDLLIMPEXP_PG wxPGProperty : public wxObject
#else
class WXDLLIMPEXP_PG wxPGProperty
#endif
{
    friend class wxPGPropertyWithChildren;
    friend class wxPropertyGrid;
    friend class wxPropertyGridState;
    //_WX_PG_DECLARE_PROPERTY_CLASS(wxPGProperty)
public:

    /** Basic constructor. Should not be necessary to override.
    */
    wxPGProperty();

    /** Constructor.
        Real used property classes should have constructor of this style:

        \code

        // If MyValueType is a class, then it should be a constant reference
        // (e.g. const MyValueType& ) instead.
        wxMyProperty ( const wxString& label, const wxString& name,
            MyValueType value ) : wxPGProperty
        {
            // Only required if MyValueType is not built-in default
            // (wxString, long, double, bool, and wxArrayString are;
            // wxFont, wxColour, etc. are not).
            wxPG_INIT_REQUIRED_TYPE(MyValueType)
            DoSetValue(value); // Generally recommended way to set the initial value.

            // If has child properties (i.e. wxPGPropertyWithChildren is used
            // as the parent class), then create children here. For example:
            //     AddChild( new wxStringProperty( wxT("Subprop 1"), wxPG_LABEL, value.GetSubProp1() ) );
        }

        \endcode

        Of course, in this example, wxPGProperty could also be wxPGPropertyWithChildren
        (if it has sub-properties) or actually any other property class.
    */
    wxPGProperty( const wxString& label, const wxString& name );

    /** Virtual destructor. It is customary for derived properties to override this. */
    virtual ~wxPGProperty();

    /** Sets property's internal value.
        \param value
        Simple container with GetString(), GetLong() etc. methods. Currently recommended
        means to extract value is to use wxPGVariantToXXX(value) macro.
        \remarks
        Example pseudo-implementation with comments:
        \code

        void wxMyProperty::DoSetValue ( wxPGVariant value )
        {
            // A) Get value. For example
            const wxMyValueType* pvalue = wxPGVariantToWxObjectPtr(value,wxMyValueType);
            //    or:
            const wxString& str = wxPGVariantToString(value);
            //    or:
            long val = wxPGVariantToLong(value);

            // B) If value is wxObject or void based with NULL default, then handle that:
            if ( pvalue )
                m_value = *pvalue;
            else
                pmyvalue->SetToDefault();

            // Otherwise
            // m_value = *pvalue;
            // is sufficient.

            // C) If has children, this should be here (before displaying in control).
            RefreshChildren();

        }

        \endcode
    */
    virtual void DoSetValue ( wxPGVariant value );

    /** Returns properly constructed wxPGVariant.
    */
    virtual wxPGVariant DoGetValue () const;

#if wxPG_EMBED_VARIANT
    /** Returns value as reference to a wxVariant.
    */
    inline const wxVariant& GetValueAsVariant () const
    {
        return *this;
    }
#else
    /** Returns value as wxVariant.
    */
    inline wxVariant GetValueAsVariant () const;
#endif

    /** Returns text representation of property's value.
        \param arg_flags
        If wxPG_FULL_VALUE is set, returns complete, storable value instead of displayable
        one (they may be different).
    */
    virtual wxString GetValueAsString ( int arg_flags = 0 ) const;

    /** Converts string to a value, and if succesfull, calls DoSetValue() on it.
        Default behaviour is to do nothing.
        \param text
        String to get the value from.
        \param report_error
        If TRUE, invalid string will be reported (prefer to use wxLogError).
        \retval
        TRUE if value was changed.
    */
    virtual bool SetValueFromString ( const wxString& text, int flags = 0 );

    /** Converts integer to a value, and if succesfull, calls DoSetValue() on it.
        Default behaviour is to do nothing.
        \param value
        Int to get the value from.
        \param flags
        If has wxPG_FULL_VALUE, then the value given is a actual value and not an index.
        \retval
        TRUE if value was changed.
    */
    virtual bool SetValueFromInt ( long value, int flags = 0 );

    /** Returns size of the custom paint image in front of property.
        Returning -1 for either dimension means using default value.
        Default behaviour is to return wxSize(0,0), which means no image.
    */
    virtual wxSize GetImageSize() const;

    /** Events received by editor widgets are processed here. Note that editor class
        usually processes most events. Some, such as button press events of
        TextCtrlAndButton class, should 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).
        \param event
        Associated wxEvent. This may be NULL, which indicates focus is leaving control.
        Property should get the edited value from wnd_primary and store it to the
        internals.
        \retval
        Should return TRUE if any changes in value should be reported. This is case,
        for example, when enter is pressed in wxTextCtrl.\n
        parent->EditorsValueWasModified() should be called on any change,
        regardless if it is not large enough to be reported. This is case,
        for example, when text in wxTextCtrl changes.
        \remarks
        Note that event is pointer, not a reference.
    */
    virtual bool OnEvent ( wxPropertyGrid* propgrid, wxPGCtrlClass* wnd_primary, wxEvent& event );

#if wxPG_INCLUDE_WXOBJECT
    inline const wxChar* GetClassName () const
    {
        return GetClassInfo()->GetClassName();
    }
#else
    /** Returns classname (for example, "wxStringProperty" for wxStringProperty)
        of a property class.
    */
    virtual const wxChar* GetClassName () const = 0;
#endif

    /** Returns string that identified the type of property's value.
        Since pointer-level identification is used for basic types,
        wxPGTypeXXX string pointers should be used as often as possible.
        Rest should return CLASSINFO(valueclass)->GetClassName().
        \sa @link typestrings wxPGTypeXXX string pointers @endlink
    */

    /** Returns pointer to the object that has methods related to
        the value type of this property. Keep atleast this method
        abstract so the class is kept abstract.
    */
    virtual const wxPGValueType* GetValueType () const = 0;

    /** Returns pointer to an instance of editor class.
    */
    virtual const wxPGEditor* GetEditorClass () const;

    /** Returns 0 for normal items. 1 for categories, -1 for other properties with children,
        -2 for wxCustomProperty (mostly like -1 ones but with few expections).
        \remarks
        Should not be overridden by new custom properties.
    */
    //virtual int GetParentingType() const;
    inline signed char GetParentingType() const { return m_parentingType; }

    /** Returns current value's index to the choice control. May also return,
        through pointer arguments, strings that should be inserted to that control.
        Irrelevant to classes which do not employ wxPG_EDITOR(Choice) or similar.
        \remarks
        - If returns -1 in choiceinfo->m_itemCount, then in that case this
          class be derived from wxBaseEnumPropertyClass (see propdev.h) and
          GetEntry is used to fill an array (slower, but handier if you don't
          store your labels as arrays of strings).
        - Must not crash even if property's set of choices is uninitialized
          (i.e. it points to wxPGGlobalVars->m_emptyConstants).
    */
    virtual int GetChoiceInfo ( wxPGChoiceInfo* choiceinfo );

    /** Override to paint an image in front of the property value text or drop-down
        list item.
        If property's GetImageSize() returns size that has height != 0 but less than
        row height ( < 0 has special meanings), wxPropertyGrid calls this method to
        draw a custom image in a limited area in front of the editor control or
        value text/graphics, and if control has drop-down list, then the image is
        drawn there as well (even in the case GetImageSize() returned higher height
        than row height).

        NOTE: Following applies when GetImageSize() returns a "flexible" height (
        using wxPG_FLEXIBLE_SIZE(W,H) macro), which implies variable height items:
        If rect.x is < 0, then this is a measure item call, which means that
        dc is invalid and only thing that should be done is to set paintdata.m_drawnHeight
        to the height of the image of item at index paintdata.m_choiceItem. This call
        may be done even as often as once every drop-down popup show.
        \param dc
        wxDC to paint on.
        \param rect
        Box reserved for custom graphics. Includes surrounding rectangle, if any.
        If x is < 0, then this is a measure item call (see above).
        \param paintdata
        wxPGPaintData structure with much useful data.
        \remarks
            - You can actually exceed rect width, but if you do so then paintdata.m_drawnWidth
              must be set to the full width drawn in pixels.
            - Due to technical reasons, rect's height will be default even if custom height
              was reported during measure call.
            - Font and text colour should not be modified.
            - Brush is guaranteed to be default background colour. It has been already used to
              clear the background of area being painted. It can be modified.
            - Pen is guaranteed to be 1-wide 'black' (or whatever is the proper colour) pen for
              drawing framing rectangle. It can be changed as well.
        \sa @link GetValueAsString @endlink
    */
    virtual void OnCustomPaint ( wxDC& dc,
        const wxRect& rect, wxPGPaintData& paintdata );

    /** Sets an attribute of this property. This is quite property class specific,
        and there are no common attributes. Note that attribute may be specific
        to a property instance, or it may affect all properties of its class.
        \param id
        Identifier of attribute
        \param value
        Value for that attribute.
    */
    virtual void SetAttribute ( int id, wxVariant value );

    /** Returns property's label. */
    inline const wxString& GetLabel() const { return m_label; }

    /** Returns wxPropertyGridState in which this property belongs. */
    wxPropertyGridState* GetParentState() const;

#if wxPG_EMBED_VARIANT
    /** Returns property's name (alternate way to access property). */
    //inline const wxString& GetName() const { return wxVariant::GetName(); }
    inline void DoSetName(const wxString& str) { SetName(str); }
#else
    /** Returns property's name (alternate way to access property). */
    inline const wxString& GetName() const { return m_name; }
    inline void DoSetName(const wxString& str) { m_name = str; }
#endif

    /** Gets pre-calculated top y coordinate of property graphics. 
        This cannot be relied on all times (wxPropertyGrid knows when :) ),
        and value is -1 if property is not visible.
    */
    inline int GetY() const { return m_y; }

    void UpdateControl ( wxPGCtrlClass* primary );

    inline wxString GetDisplayedString () const
    {
        return GetValueAsString(0);
    }

    /** Returns property id. */
    inline wxPGId GetId() { return wxPGIdGen(this); }

    /** Return parent of property */
    inline wxPGPropertyWithChildren* GetParent() const { return m_parent; }

    /** Returns true if property is valid and wxPropertyGrid methods
        can operate on it safely.
    */
    inline bool IsOk() const
    {
        return (( m_y >= -1 )?TRUE:FALSE);
    }

    inline bool IsFlagSet( unsigned char flag ) const
    {
        return ( m_flags & flag ) ? TRUE : FALSE;
    }

    /** Returns true if extra children can be added for this property
        (i.e. it is wxPropertyCategory or wxCustomProperty)
    */
    inline bool CanHaveExtraChildren() const
    {
        return ( m_parentingType == 1 || m_parentingType == -2 );
    }

    inline unsigned int GetFlags() const
    {
        return (unsigned int)m_flags;
    }

    /** Returns type name of property that is compatible with CreatePropertyByType.
        and wxVariant::GetType.
    */
    inline const wxChar* GetType() const
    {
        return GetValueType()->GetType();
    }

    /** Returns TRUE if this is a sub-property. */
    inline bool IsSubProperty() const
    {
        wxPGProperty* parent = (wxPGProperty*)m_parent;
        if ( parent && parent->GetParentingType() < 0 && parent->m_y > -2 )
            return TRUE;
        return FALSE;
    }

    /** Returns number of children (always 0 for normal properties). */
    size_t GetChildCount() const;

    inline unsigned int GetArrIndex() const { return m_arrIndex; }

    inline unsigned int GetDepth() const { return (unsigned int)m_depth; }

    /** Returns position in parent's array. */
    inline unsigned int GetIndexInParent() const
    {
        return (unsigned int)m_arrIndex;
    }

    /** If property has choices and they are not yet private, new such copy
        of them will be created.
    */
    void SetChoicesPrivate();

    inline void SetFlag( unsigned char flag ) { m_flags |= flag; }

    inline void SetHelpString ( const wxString& help_string ) { m_helpString = help_string; }

    inline void SetLabel( const wxString& label ) { m_label = label; }

#if wxPG_USE_VALIDATORS
    /** Sets wxValidator for a property*/
    void SetValidator ( wxPropertyValidator& validator );

    /** Gets assignable version of property's validator. */
    wxPropertyValidator& GetValidator () const;