pg_dox_mainpage.h

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

      wxTheClipboard->Flush() before exiting.
    - Atleast with wxGTK2+Unicode+Debug Mode File Selector dialog may trigger an assertion
      failure (line 1060 in string.cpp with 2.5.3) that can be cancelled
      probably without any ill-effect.

    Following only apply when <b>not</b> using custom controls:
    - Under GTK, EVT_MOTION does not trigger for child control. Causes cursor change
      inconsistencies. Permanent mouse capture is not practical since it causes wxWindow::
      SetCursor to fail (and events cannot be relayed to native controls anyway).
      Easy solution used: Splitter drag detect margin and control do not overlap.
    - When splitter is being dragged, active editor control (button as well under wxGTK)
      is hidden to prevent flickering. This may go unnoticed with some
      controls (wxTextCtrl) but is very noticeable with others (wxChoice).
    - Under MSW, when resizing, editor controls flicker. No easy fix here
      (wxEVT_ONIDLE might be employed).
    - Under GTK 1.2, font may show invisible if it is not bold (so it is forced).
    - Under wxGTK, controls may flicker a bit (actually, a lot) when being shown.

    \section todo Todo
    For a detailed TODO, see propertygrid.cpp (just search for "todo" and you'll find it).

    \section notes Design Notes
    - Currently wxPropertyGridManager uses "easy" way to relay events from embedded
      wxPropertyGrid. That is, the exact same id is used for both.

    - wxHashMap used to access properties by name uses 'const wxChar*' instead of 'wxString'.
      Altough this has somewhat lower performance if used mostly with wxStrings, it is much
      faster if a lot of non-wxString strings are used, since they don't have to be
      recreated as wxString before using with the hashmap.
      If you want to change this behaviour, see propertygrid.h. Comment current version
      (including wxPGNameStr), and uncomment version that uses wxString.
      Note that with unicode, wxString is always used (due to some weird issues).

    - If wxPG_DOUBLE_BUFFER is 1 (default for MSW, GTK and MAC), wxPropertyGrid::OnDrawItems
      composes the image on a wxMemoryDC. This effectively eliminates flicker caused by drawing
      itself (property editor controls are another matter).

    - Under wxMSW, flicker freedom with native editor controls is achieved by creating them
      at 'out of sight' position, then hiding&freezing them, then moving them to the
      correct position, and finally thawing&showing them.

    \section crossplatform Crossplatform Notes

    - GTK1: When showing a dialog you may encounter invisible font!
      Solution: Set parent's font using SetOwnFont instead of SetFont.

    - GTK: Your own control can overdraw wxGTK wxWindow border!

    - wxWindow::SetSizeHints may be necessary to shrink controls below certain treshold,
      but only on some platforms. For example wxMSW might allow any shrinking without
      SetSizeHints call where wxGTK might not.

    - GTK Choice (atleast, maybe other controls as well) likes its items set
      in constructor. Appending them seems to be slower (Freeze+Thaw won't help).
      Even using Append that gets wxArrayString argument may not be good, since it
      may just append every string one at a time.

    \section newprops Creating New Properties

    <b>Note:</b> This section is under construction!

    Each property class represents a specialized value storage for a value type.
    It also nominates an editor class to itself, and implements some helper
    methods to complement the used value type and editor classes.

    Easiest way to create a new property is to use one of the supplied
    macro pairs (see the section below).

    \remarks
    - Code that implements a property generally requires inclusion of
      wx/propgrid/propdev.h.
    - Read wxPGProperty and wxPGPropertyWithChildren class documentation to
      find out what each overriddable method should do.

    \subsection methoda Macro Pairs

    \subsubsection custstringprop String Property with Button

    This custom property will be exactly the same as wxLongStringProperty,
    except that you can specify a custom code to handle what happens
    when the button is pressed.

      In header:
        \code
        WX_PG_DECLARE_STRING_PROPERTY(PROPNAME)
        \endcode

        In source:
        \code

        #include <wx/propgrid/propdev.h>

        WX_PG_IMPLEMENT_STRING_PROPERTY(PROPNAME)
        bool PROPNAMEClass::OnButtonClick ( wxPropertyGrid* propgrid, wxString& value )
        {
            //
            // TODO: Show dialog, read initial string from value. If changed,
            //   store new string to value and return TRUE.
            //
        }
        \endcode

    \subsubsection custflagsprop Custom Flags Property
    Flags property with custom default value and built-in labels/values.

    In header:
        \code
        WX_PG_DECLARE_CUSTOM_FLAGS_PROPERTY(PROPNAME)
        \endcode

    In source:
        \code

        #include <wx/propgrid/propdev.h>

        // LABELS, VALUES and ITEMCOUNT are as in the arguments to wxFlagsProperty
        // constructor. DEFVAL is the new default value (normally it is 0).
        WX_PG_IMPLEMENT_CUSTOM_FLAGS_PROPERTY(PROPNAME,LABELS,VALUES,ITEMCOUNT,DEFAULT_FLAGS)
        \endcode

    The new property class will have simple (label,name,value) constructor.

    \subsubsection custenumprop Custom EnumProperty

    Exactly the same as custom FlagsProperty. Simply replace FLAGS with ENUM in
    macro names to create wxEnumProperty based class instead.

    \subsubsection custarraystringprop Custom ArrayString property

    This type of custom property allows selecting different string delimiter
    (default is '"' on both sides of the string - as in C code), and allows
    adding custom button into the editor dialog.

    In header:
        \code
        WX_PG_DECLARE_ARRAYSTRING_PROPERTY(wxMyArrayStringProperty)
        \endcode

    In source:

        \code

        #include <wx/propgrid/propdev.h>

        // second argument = string delimiter. '"' for C string style (default),
        //    and anything else for str1<delimiter> str2<delimiter> str3 style
        //    (so for example, using ';' would result to str1; str2; str3).
        // third argument = const wxChar* text for the custom button. If NULL
        //    then no button is added.
        WX_PG_IMPLEMENT_ARRAYSTRING_PROPERTY(wxMyArrayStringProperty,',',wxT("Browse"))

        bool wxMyArrayStringPropertyClass::OnCustomStringEdit (wxWindow* parent,
                                                               wxString& value)
        {
            //
            // TODO: Show custom editor dialog, read initial string from value.
            //   If changed, store new string to value and return TRUE.
            //
        }

        \endcode

    \subsubsection custcolprop Custom ColourProperty

    wxColourProperty/wxSystemColourProperty that can have custom list of colours
    in dropdown.

    Use version that doesn't have _USES_WXCOLOUR in macro names to have
    wxColourPropertyValue as value type instead of plain wxColour (in this case
    values array might also make sense).

    In header:
        \code
        #include <wx/propgrid/advprops.h>
        WX_PG_DECLARE_CUSTOM_COLOUR_PROPERTY_USES_WXCOLOUR(wxMyColourProperty)
        \endcode

    In source:

        \code

        #include <wx/propgrid/propdev.h>

        // Colour labels. Last (before NULL, if any) must be Custom.
        static const wxChar* mycolprop_labels[] = {
            wxT("Black"),
            wxT("Blue"),
            wxT("Brown"),
            wxT("Custom"),
            (const wxChar*) NULL
        };

        // Relevant colour values as unsigned longs.
        static unsigned long mycolprop_colours[] = {
            wxPG_COLOUR(0,0,0),
            wxPG_COLOUR(0,0,255),
            wxPG_COLOUR(166,124,81),
            wxPG_COLOUR(0,0,0)
        };

        // Implement property class. Third argument is optional values array,
        // but in this example we are only interested in creating a shortcut
        // for user to access the colour values. Last arg is itemcount, but
        // that's not necessary because our label array is NULL-terminated.
        WX_PG_IMPLEMENT_CUSTOM_COLOUR_PROPERTY_USES_WXCOLOUR(wxMyColourProperty,
                                                             mycolprop_labels,
                                                             (long*)NULL,
                                                             mycolprop_colours,
                                                             0)
        \endcode

    \subsection declaring Declaring an Arbitrary Property

    To make your property available globally, you need to declare it in a
    header file. Usually you would want to use WX_PG_DECLARE_PROPERTY
    macro to do that (it is in propgrid.h). It has three arguments: PROPNAME,
    T_AS_ARG and DEFVAL. PROPNAME is property NAME, T_AS_ARG is type input
    in function argument list ( "int" for int value type, "const wxString&" for
    wxString value type, etc.), and DEFVAL is default value for that.

    For example:

    \code

        // Declare wxRealPoint Property
        WX_PG_DECLARE_PROPERTY(wxRealPointProperty,const wxRealPoint&,wxRealPoint(0.0,0.0))

    \endcode

    There is also WX_PG_DECLARE_PROPERTY_WITH_DECL which takes an additional declaration
    argument (export ,for example, when exporting from a dll).

    If you want that your property could be inherited from, then you would also
    have to define the class body in the header file. In most cases this is not
    necessary and the class can be defined and implemented completely in the source.

    \subsection designtypes Design Types of Properties

    When speaking from an object design perspective, there are basicly five different
    types of properties:

    <b>Basic</b>: These derive directly from base abstract property class (wxPGProperty).
    By far the most commonly used design type.

    <b>With Children</b>: These derive directly from base abstract parent property class
    (wxPGPropertyWithChildren). Font property and flags property, for example, are
    of this design type.

    <b>Inherited</b>: These are inherited from a working property class but do not
    use the same value type (for example, SystemColour property inherits from
    Enum property but has different value type).

    <b>Simple Inherited</b>: These are inherited from a working property class and
    use the same value type (for example, Cursor property inherits from
    Enum property and uses the same value type).

    <b>Inherited With Subset Value</b>: These are like Simple Inherited but they
    do not use the same value type. However, they *do* use the same value data
    to store a subset of the parent class' value (for example, Colour property
    has subset of SystemColour property's value).

    \subsection implementing Implementing a Property

    First there is class body with WX_PG_DECLARE_PROPERTY_CLASS (or similar) macro,
    constructor, virtual destructor, and declarations for other overridden
    methods. Then comes WX_PG_IMPLEMENT_PROPERTY_CLASS (or similar) macro, and
    after that class method implementations.

    \subsection Tips

    - To get property's parent grid, call GetParentState()->GetGrid()

    \subsection valuetypes Creating New Value Types

    If you want to a property to use a value type that is not among the
    builtin types, then you need to create a new property value type. It is
    quite straightforward, using two macros.

    In header, use WX_PG_DECLARE_VALUE_TYPE(DATATYPE), like this:

    \code
        // Example: Declare value type for wxRealPoint.
        WX_PG_DECLARE_VALUE_TYPE(wxRealPoint)
    \endcode

    If, however, class of your value type does not inherit from
    wxObject, and you need to use it in wxVariant list used as a
    persistent storage (for example, see wxPropertyGrid::GetPropertyValues),
    then use this instead, as it also declares a necessary wxVariantData_DATATYPE
    class.

    \code
        // Example: Declare value type and wxVariantData class for wxRealPoint.
        WX_PG_DECLARE_VALUE_TYPE_VOIDP(wxRealPoint)
    \endcode

    There are also _WITH_DECL versions of both.

    However, there are a few different implement macros to place in
    a source file. Pick one according to the type of type.

    \code

        // For implementing value type for a wxObject based class.
        WX_PG_IMPLEMENT_VALUE_TYPE_WXOBJ(TYPE,DEFPROPERTY,DEFVAL)

        // Same as above, except that an instance of TYPE is
        // stored in class. Thus, DEFVAL can be any expression
        // that can be assigned to the type.
        WX_PG_IMPLEMENT_VALUE_TYPE_WXOBJ_OWNDEFAULT(TYPE,DEFPROPERTY,DEFVAL)

        // For implementing value type for a non-wxObject based class.
        // Like with ...WXOBJ_OWNDEFAULT macro above, instance of TYPE
        // is stored and DEFVAL can be any expression.
        WX_PG_IMPLEMENT_VALUE_TYPE_VOIDP_SIMPLE(TYPE,DEFPROPERTY,DEFVAL) 

        // Like above, but also implement the wxVariantData class
        // declared with the second type value type declare macro.
        WX_PG_IMPLEMENT_VALUE_TYPE_VOIDP(TYPE,DEFPROPERTY,DEFVAL) 

        // Like above, but accepts a custom wxVariantData class.
        WX_PG_IMPLEMENT_VALUE_TYPE_VOIDP_CVD(TYPE,DEFPROPERTY,DEFVAL,VARIANTDATACLASS) 

        // For implementing value type with different default value.
        WX_PG_IMPLEMENT_DERIVED_TYPE(TYPENAME,PARENTVT,DEFVAL)

        // For implementing value type for a native value.
        // Generally should not be used since it is meant for
        // wxString, int, double etc. which are already implemented.
        WX_PG_IMPLEMENT_VALUE_TYPE(TYPE,DEFPROPERTY,TYPESTRING,GETTER,DEFVAL)

    \endcode

    Argument descriptions:

    TYPE - Actual data type represented by the value type, or if
      derived type, any custom name.

    DEFPROPERY - Name of the property that will edit this
      value type by default.

    DEFVAL - Default value for the property.

    TYPENAME - An arbitraty typename for this value type. Applies
      only to the derived type.

    PARENTVT - Name of parent value type, from which this derived
      type inherits from.

    \remarks
    - Your class, which you create value type for, must have a
      copy constructor.

*/

#endif // __WX_PG_DOX_MAINPAGE_H__