pg_dox_mainpage.h

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

    - May have children.
    - Editor class (wxPG_CUSTOM_EDITOR).
    - Image in front of value (wxPG_CUSTOM_IMAGE,wxPG_CUSTOM_PAINT_CALLBACK).
    - What happens when editor's button is pressed (wxPG_CUSTOM_CALLBACK).

    For more info on attributes, see \ref attrids. In sample application,
    there is a CustomProperty property that has children that can be
    used to modify the property itself.

    <b>Limitations:</b>
    - Currently wxCustomProperty is limited to wxString value type.

    \remarks
    - Since image is not resized to fit, only cropped, you must resize
      the it, if necessary, before setting it as wxPG_CUSTOM_IMAGE
      attribute. Use wxPropertyGrid::GetImageSize to get preferred
      image size (maximum width should be 64).
    - If you need to have property editors other than those supplied,
      please see wxPGEditor docs and source code in propgrid.cpp.

    \code

        //
        // Sample code for adding wxCustomProperty
        //
    
        wxPGId cpId = pg->Append( wxCustomProperty(wxT("Shape"),wxPG_LABEL) );

        // Can have children
        pg->AppendIn( cpId, wxStringProperty(wxT("Label"),
                                             wxT("Shape_Label"),
                                             wxT("Shape 1")) );

        // Set choice editor
        pg->SetPropertyAttribute( cpId, wxPG_CUSTOM_EDITOR, wxPGEditor_Choice );

        wxPGConstants choices;
        choices.Add(wxT("Line"));
        choices.Add(wxT("Triangle"));
        choices.Add(wxT("Rectangle"));
        choices.Add(wxT("Circle"));

        // Set items to choose from
        pg->SetPropertyChoices( cpId, choices );

    \endcode


    \section compiling Compiling wxPropertyGrid

      Actual build process is described in readme.txt, so here is only information
    about compile options. Define these in library project settings, makefile, or if
    you prefer, at the top of propgrid.h.

    <b>wxPG_USE_CUSTOM_CONTROLS:</b> Default is 0. If set to 1, non-wxWindow based custom
    controls are used instead of normal controls. This will provide cleaner, less flickering
    appearance, but combobox may have less features and act a bit differently and textctrl
    has only generic key combinations.

    \section usage2 Using wxPropertyGridManager

    wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid,
    which can optionally have toolbar for mode and page selection, help text box,
    and a compactor button.

    wxPropertyGridManager mirrors most non-visual methods of wxPropertyGrid, some
    identically, some so that they can affect a property on any page, and some
    so that they can only affect selected target page.

    Generally, methods that operate on a property ( such as
    GetPropertyValue, SetPropertyValue, EnableProperty, LimitPropertyEditing, Delete, etc. ),
    work globally (so the given property can exist on any managed page).

    Methods that add properties ( Append, Insert, etc.) or operate on multiple properties
    (such as GetPropertyValues or SetPropertyValues), will work in target page only.
    Use SetTargetPage(index) method to set current target page. Changing a displayed page
    (using SelectPage(index), for example) will automatically set the target page
    to the one displayed.

    Global methods such as ExpandAll generally work on the target page only.

    Visual methods, such as SetCellBackgroundColour and GetNextVisible are only
    available in wxPropertyGrid. Use wxPropertyGridManager::GetGrid() to obtain
    pointer to it.

    wxPropertyGridManager constructor has exact same format as wxPropertyGrid
    constructor, and basicly accepts same extra window style flags (albeit also
    has some extra ones).

    Here's some example code for creating and populating a wxPropertyGridManager:

    \code

        wxPropertyGridManager* pgMan = new wxPropertyGridManager(this, PGID,
            wxDefaultPosition, wxDefaultSize,
            // These and other similar styles are automatically
            // passed to the embedded wxPropertyGrid.
            wxPG_BOLD_MODIFIED|wxPG_SPLITTER_AUTO_CENTER|
            // Include toolbar.
            wxPG_TOOLBAR |
            // Include description box.
            wxPG_DESCRIPTION |
            // Include compactor.
            wxPG_COMPACTOR |
            // Plus defaults.
            wxPGMAN_DEFAULT_STYLE
           );

        // Adding a page sets target page to the one added, so
        // we don't have to call SetTargetPage if we are filling
        // it right after adding.
        pgMan->AddPage(wxT("First Page"));

        pgMan->AppendCategory(wxT("Category A1"));

        // Remember, the next line equals pgman->Append( wxIntProperty(wxT("Number"),wxPG_LABEL,1) );
        pgMan->Append( wxT("Number"),wxPG_LABEL,1 );

        pgMan->Append( wxColourProperty(wxT("Colour"),wxPG_LABEL,*wxWHITE) );

        pgMan->AddPage(wxT("Second Page"));

        pgMan->Append( wxT("Text"),wxPG_LABEL,wxT("(no text)") );

        pgMan->Append( wxFontProperty(wxT("Font"),wxPG_LABEL) );

        // For total safety, finally reset the target page.
        pgMan->SetTargetPage(0);

    \endcode

    \section misc Miscellaneous Topics

    \subsection boolproperty wxBoolProperty

      There are few points about wxBoolProperty that require futher discussion:
      - wxBoolProperty can be shown as either normal combobox, checkbox, or
        a combobox which cycles when double-clicked. Property attribute
        wxPG_BOOL_USE_CHECKBOX sets property to use checkbox, while
        wxPG_BOOL_USE_DOUBLE_CLICK_CYCLING causes it to become double-click
        cycled combo box. For example, if you have a wxFlagsProperty, you can
        set its all items to use double-click cycling using the following:
        \code
            pg->SetPropertyAttribute(wxT("MyFlagsProperty"),wxPG_BOOL_USE_DOUBLE_CLICK_CYCLING,(long)1,wxRECURSE);
        \endcode

      - Default item names for wxBoolProperty are [False,True]. This can be
        changed using wxPropertyGrid::SetBoolChoices(true_choice,false_choice).

    \section proplist Property Descriptions

    Here are descriptions of built-in properties, with attributes
    (see wxPropertyGrid::SetPropertyAttribute) that apply to them.

    \subsection wxPropertyCategory

    <b>Inheritable Class:</b> wxPropertyCategoryClass.

    Not an actual property per se, but a header for a group of properties.

    \subsection wxParentProperty

    Pseudo-property that can have sub-properties inserted under itself.
    Has textctrl editor that allows editing values of all sub-properties
    in a one string. In essence, it is a category that has look and feel
    of a property, and which children can be edited via the textctrl.

    \subsection wxStringProperty

    Simple string property.

    \subsection wxIntProperty

    Like wxStringProperty, but converts text to a signed long integer.

    \subsection wxUIntProperty

    Like wxIntProperty, but displays value as unsigned int. To set
    the prefix used globally, manipulate wxPG_UINT_PREFIX string attribute.
    To set the globally used base, manipulate wxPG_UINT_BASE int
    attribute. Regardless of current prefix, understands (hex) values starting
    with both "0x" and "$".

    \subsection wxFloatProperty

    Like wxStringProperty, but converts text to a double-precision floating point.
    Default float-to-text precision is 6 decimals, but this can be changed
    by modifying wxPG_FLOAT_PRECISION attribute.

    \subsection wxBoolProperty

    Represents a boolean value. wxChoice is used as editor control, by the
    default. wxPG_BOOL_USE_CHECKBOX attribute can be set to 1 inorder to use
    check box instead.

    \subsection wxLongStringProperty

    <b>Inheritable Class:</b> wxLongStringPropertyClass

    Like wxStringProperty, but has a button that triggers a small text editor
    dialog.

    \subsection wxDirProperty

    Like wxLongStringProperty, but the button triggers dir selector instead.

    \subsection wxFileProperty

    <b>Inheritable Class:</b> wxFilePropertyClass

    Like wxLongStringProperty, but the button triggers file selector instead.
    Default wildcard is "All files..." but this can be changed by setting
    wxPG_FILE_WILDCARD attribute (see wxFileDialog for format details).
    Attribute wxPG_FILE_SHOW_FULL_PATH can be set to 0 inorder to show
    only the filename, not the entire path.

    \subsection wxEnumProperty

    <b>Inheritable Class:</b> wxEnumPropertyClass

    Represents a single selection from a list of choices - wxChoice is used
    to edit the value.

    \subsection wxFlagsProperty

    <b>Inheritable Class:</b> wxFlagsPropertyClass

    Represents a bit set that fits in a long integer. wxBoolProperty sub-properties
    are created for editing individual bits. Textctrl is created to manually edit
    the flags as a text; a continous sequence of spaces, commas and semicolons 
    is considered as a flag id separator.
    \remarks
    You cannot change children (flags) of this property directly, instead
    you can user wxPropertyGrid::ReplaceProperty to replace it with one
    that has new items.

    \subsection wxArrayStringProperty

    <b>Inheritable Class:</b> wxArrayStringPropertyClass

    Allows editing of a list of strings in wxTextCtrl and in a separate dialog.

    \subsection wxMultiChoiceProperty

    Allows editing a multiple selection from a list of strings. This is
    property is pretty much built around concept of wxMultiChoiceDialog.

    \subsection wxImageFileProperty

    <b>Inheritable Class:</b> wxImageFilePropertyClass

    Like wxFileProperty, but has thumbnail of the image in front of
    the filename and autogenerates wildcard from available image handlers.

    \subsection wxColourProperty

    Represents wxColour. wxChoice is used to edit the value. Drop-down list
    has few basic colour choices.

    \subsection wxFontProperty

    Represents wxFont. Various sub-properties are used to edit individual
    subvalues.

    \subsection wxSystemColourProperty

    <b>Inheritable Class:</b> wxSystemColourPropertyClass

    Represents wxColour and a system colour index. wxChoice is used to edit
    the value. Drop-down list has color images.

    \subsection wxCursorProperty

    Represents a wxCursor. wxChoice is used to edit the value.
    Drop-down list has cursor images under some (wxMSW) platforms.

    \subsection wxCustomProperty

    <b>Inheritable Class:</b> wxCustomPropertyClass

    A customizable property class with string data type. Value image, Editor class,
    and children can be modified.

    \subsection Additional Sample Properties

    Sample application has following additional examples of custom properties:
    - wxFontDataProperty ( edits wxFontData )
    - wxPointProperty ( edits wxPoint )
    - wxSizeProperty ( edits wxSize )
    - wxAdvImageFileProperty ( like wxImageFileProperty, but also has a drop-down for recent image selection)
    - wxDirsProperty ( edits a wxArrayString consisting of directory strings)
    - wxArrayDoubleProperty ( edits wxArrayDouble )

    \section userhelp Using wxPropertyGrid

    This is a short summary of how a wxPropertyGrid is used (not how it is programmed),
    or, rather, how it <b>should</b> behave in practice.

    - Basic mouse usage is as follows:\n
      - Clicking property label selects it.
      - Clicking property value selects it and focuses to editor control.
      - Clicking category label selects the category.
      - Double-clicking category label selects the category and expands/collapses it. 
      - Double-clicking labels of a property with children expands/collapses it.

    - Keyboard usage is as follows:\n
      When editor control is not focused:\n
      - cursor up - moves to previous visible property\n
      - cursor down - moves to next visible property\n
      - cursor left - if collapsible, collapses, otherwise moves to previous property\n
      - cursor right - if expandable, expands, otherwise moves to next property\n
      - tab (if enabled) - focuses keyboard to the editor control of selected property\n
      When editor control is focused:\n
      - tab - moves to next visible property\n
      - shift-tab - moves to previous visible property\n
      - escape - unfocuses from editor control\n

    - wxTextCtrl / wxCustomTextCtrl based editors only report that value has actually
      changed if text was changed and return was pressed afterwards.

    - In long strings tabs are represented by "\t" and line break by "\n".

    \section bugs Known Bugs
    Any insight on these is more than welcome.
    - wxGTK: Pressing ESC to unfocus an editor control will screw the focusing
      (either focuses back to the editor or moves focus to limbo; works perfectly
      on wxMSW though).
    - I have experienced a complete freeze when toying with the popup of
      wxAdvImageProperty. Visiting another window will end it.
    - wxGTK: in sample application, property text colour is not set correct from
      wxSystemColourProperty. Value is correct, but the resulting text colour
      is sometimes a bit skewed if it is not a shade of gray. This may be GTK's
      attempt to auto-adjust it.
    - wxGTK: Sometimes '...' text on editor button may disappear (maybe
      "invisible font" related thingie). wxAdvImageProperty never seem to get
      the text, while other controls do.
    Following are wxWidgets or platform bugs:
    - wxWidgets <= 2.5.2: No proper uxtheme (WinXP buttons etc). No keyboard
      navigation out of grid. Possibly other nasty problems.
    - wxWidgets <= 2.5.3: No mouse wheel scrolling in drop down lists.
    - wxWidgets <= 2.5.5: wxGTK: No proper static text wrapping, so help box text
      may appear incorrectly.
    - wxMSW: After (real) popup window is shown in wxPropertyGrid, grid's scrollbar
      won't get hilight until another window is visited. This is probably a Windows
      bug.
    - wxGTK+ w/ unicode: image handlers return only the first character of an extension
    - wxGTK+ 1.2: Controls sometimes disappear. They reappear when cursor is moved
      over them.
    - wxGTK+ 1.2: Cannot set (multiple) items for wxListBox (affects
      wxMultiChoiceProperty).

    \section issues Issues
    These are not bugs per se, but miscellaneous cross-platform issues that have been
    resolved in a less-than-satisfactory manner.
    - wxMSW: Toolbar's ToggleTool doesn't disable last item in the same radiogroup. AFAIK,
      there is no way to do that.
    - wxMSW: wxCCustomTextCtrl copy-pasting causes memory leak unless app calls