pg_dox_mainpage.h

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

/////////////////////////////////////////////////////////////////////////////
// Name:        pg_dox_mainpage.h
// Purpose:     wxPropertyGrid Doxygen Documentation
// Author:      Jaakko Salli
// Modified by:
// Created:     Oct-08-2004
// RCS-ID:      $Id:
// Copyright:   (c) Jaakko Salli
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

#ifndef __WX_PG_DOX_MAINPAGE_H__
#define __WX_PG_DOX_MAINPAGE_H__

/**
    \mainpage wxPropertyGrid Overview

      wxPropertyGrid is a specialized two-column grid for editing properties
    such as strings, numbers, flagsets, fonts, and colours. It allows hierarchial,
    collapsible properties ( via so-called categories that can hold child
    properties), sub-properties, and has strong wxVariant support (for example,
    allows populating from near-arbitrary list of wxVariants).

    Classes:\n
      wxPropertyGrid\n
      wxPropertyGridManager\n
      wxPropertyGridEvent\n

    Header files:\n
      <b>wx/propgrid/propgrid.h:</b> Mandatory when using wxPropertyGrid.\n
      <b>wx/propgrid/advprops.h:</b> For less often used property classes.\n
      <b>wx/propgrid/manager.h:</b> Mandatory when using wxPropertyGridManager.\n
      <b>wx/propgrid/propdev.h:</b> Mandatory when implementing custom property classes.\n

    \ref basics\n
    \ref categories\n
    \ref parentprops\n
    \ref enumandflags\n
    \ref advprops\n
    \ref operations\n
    \ref events\n
    \ref populating\n
    \ref custprop\n
    \ref usage2\n
    \ref compiling\n
    \ref misc\n
    \ref proplist\n
    \ref userhelp\n
    \ref bugs\n
    \ref issues\n
    \ref todo\n
    \ref notes\n
    \ref newprops\n

    \section basics Creating and Populating wxPropertyGrid

    As seen here, wxPropertyGrid is constructed in the same way as
    other wxWidgets controls:

    \code

    // Necessary header file
    #include <wx/propgrid/propgrid.h>

    ...

        // Assumes code is in frame/dialog constructor

        // Construct wxPropertyGrid control
        wxPropertyGrid* pg = new wxPropertyGrid(
            this, // parent
            PGID, // id
            wxDefaultPosition, // position 
            wxDefaultSize, // size
            // Some specific window styles - for all additional styles, see the documentation
            wxPG_AUTO_SORT | // Automatic sorting after items added
            wxPG_BOLD_MODIFIED | // Modified values are drawn in bold font
            wxPG_SPLITTER_AUTO_CENTER | // Automatically center splitter until user manually adjusts it
            // Default style
            wxPG_DEFAULT_STYLE
            );

    \endcode

      (for complete list of new window styles: @link wndflags Additional Window Styles@endlink)

      wxPropertyGrid is usually populated with lines like this:

    \code
        pg->Append( wxStringProperty(wxT("Label"),wxT("Name"),wxT("Initial Value")) );
    \endcode

    wxStringProperty is a constructor function that creates a property instance of
    a property class "wxStringProperty". Only the first function argument (label)
    is mandatory. When necessary, name defaults to label and initial value to
    default value. If wxPG_LABEL is used as the name argument, then the label is
    automatically used as a name as well (this is more efficient than manually
    defining both as the same). Empty name is also allowed, but in this case the
    property cannot be accessed by its name.

    To demonstrate other common property classes, here's another code snippet:

    \code

        // Add int property 
        pg->Append ( wxIntProperty ( wxT("IntProperty"), wxPG_LABEL, 12345678 ) );

        // Add float property (value type is actually double)
        pg->Append ( wxFloatProperty ( wxT("FloatProperty"), wxPG_LABEL, 12345.678 ) );

        // Add a bool property
        pg->Append ( wxBoolProperty ( wxT("BoolProperty"), wxPG_LABEL, false ) );

        // A string property that can be edited in a separate editor dialog.
        pg->Append ( wxLongStringProperty (wxT("LongStringProperty"),
                                           wxPG_LABEL,
                                           wxT("This is much longer string than the ")
                                           wxT("first one. Edit it by clicking the button.")));

        // String editor with dir selector button.
        pg->Append ( wxDirProperty( wxT("DirProperty"), wxPG_LABEL, ::wxGetUserHome()) );

        // A file selector property.
        pg->Append ( wxFileProperty( wxT("FileProperty"), wxPG_LABEL, wxEmptyString ) );

        // Extra: set wildcard for file property (format same as in wxFileDialog).
        pg->SetPropertyAttribute(wxT("TextFile"),
                                 wxPG_FILE_WILDCARD,
                                 wxT("All files (*.*)|*.*"));

    \endcode

    \section categories Categories

      wxPropertyGrid has a hierarchial property storage and display model, which
    allows property categories to hold child properties and even other
    categories. Other than that, from the programmer's point of view, categories
    can be treated exactly the same as "other" properties. For example, despite
    its name, GetPropertyByName also returns a category by name, and SetPropertyLabel
    also sets label of a category. Note however that sometimes the label of a
    property category may be referred as caption (for example, there is
    SetCaptionForegroundColour method that sets text colour of a property category's label).

      When category is added at the top (i.e. default) level of the hierarchy,
    it becomes a *current category*. This means that all other (non-category)
    properties after it are automatically added to it. You may add
    properties to specific categories by using wxPropertyGrid::Insert or wxPropertyGrid::AppendIn.

      Category code sample:

    \code

        // One way to add category (similar to how other properties are added)
        pg->Append( wxPropertyCategory(wxT("Main")) );

        // All these are added to "Main" category
        pg->Append( wxStringProperty(wxT("Name")) );
        pg->Append( wxIntProperty(wxT("Age"),wxPG_LABEL,25) );
        pg->Append( wxIntProperty(wxT("Height"),wxPG_LABEL,180) );
        pg->Append( wxIntProperty(wxT("Weight")) );

        // Another way
        pg->AppendCategory( wxT("Attributes") );

        // All these are added to "Attributes" category
        pg->Append( wxIntProperty(wxT("Intelligence")) );
        pg->Append( wxIntProperty(wxT("Sensibility")) );
        pg->Append( wxIntProperty(wxT("Agility")) );
        pg->Append( wxIntProperty(wxT("Coordination")) );
        pg->Append( wxIntProperty(wxT("Constitution")) );
        pg->Append( wxIntProperty(wxT("Strength")) );
        pg->Append( wxIntProperty(wxT("Personality")) );
        pg->Append( wxIntProperty(wxT("Appearance")) );
        pg->Append( wxIntProperty(wxT("Bravado")) );
        pg->Append( wxIntProperty(wxT("Willpower")) );

    \endcode

    \section parentprops Parent Properties

      If you want to combine number of properties under single parent (just
    like wxFontProperty combines font attributes), then the easiest way to
    proceed is to use wxParentProperty.

    \remarks
    - wxParentProperty's value type is string.
    - Child property that has children of its own will be embedded in
      braces ([]).

    Sample:

    \code
        wxPGId pid = pg->Append( wxParentProperty(wxT("Car"),wxPG_LABEL) );

        pg->AppendIn( pid, wxStringProperty(wxT("Model")), wxPG_LABEL,
                                            wxT("Lamborghini Diablo SV")) );

        pg->AppendIn( pid, wxIntProperty(wxT("Engine Size (cc)"),
                                         wxPG_LABEL,
                                         5707) );

        wxPGId speedId = pg->AppendIn( pid, wxParentProperty(wxT("Speeds"),wxPG_LABEL) );
        pg->AppendIn( speedId, wxIntProperty(wxT("Max. Speed (mph)"),wxPG_LABEL,300) );
        pg->AppendIn( speedId, wxFloatProperty(wxT("0-100 mph (sec)"),wxPG_LABEL,3.9) );
        pg->AppendIn( speedId, wxFloatProperty(wxT("1/4 mile (sec)"),wxPG_LABEL,8.6) );

        pg->AppendIn( pid, wxIntProperty(wxT("Price ($)"),
                                         wxPG_LABEL,
                                         300000) );

        // Displayed value of "Car" property is now:
        // "Lamborghini Diablo SV; [300; 3.9; 8.6]; 300000"

    \endcode


    \section enumandflags wxEnumProperty and wxFlagsProperty

      wxEnumProperty is used when you want property's (integer) value
    to be selected from a popup list of choices.

      Creating wxEnumProperty is more complex than those described earlier.
    You have to provide list of constant labels, and optionally relevant values
    (if given indexes are not used).

      As of 1.0.0rc1, wxEnumProperty actually stores string and value
    arrays given to it, but in such manner that the same storage can be reused
    for properties that use the exact same array pointers.

    \remarks

    - Value wxPG_INVALID_VALUE (equals 2147483647 equals 2^31-1) is not
      allowed as value.

    - Altough you can use label and value arrays that are temporary
      variables, it is recommended that you make them persistent (i.e. static or
      global) in practical code. <b>Otherwise there is a slight probability that
      property will use wrong set of choices or that the allocation
      of choices becomes very inefficient.</b> Only exception is
      wxPGConstants, which can be used as a temporary variable (see below).

    A very simple example:

    \code

    static const wxChar* gs_array_diet[] = 
        { wxT("Herbivore"), wxT("Carnivore"), wxT("Omnivore"), NULL };

        ...

        pg->Append( wxEnumProperty(wxT("Diet"),
                                   wxPG_LABEL,
                                   gs_array_diet) );

    \endcode

    Now with real values (and more comments):

    \code

        //
        // wxEnumProperty actually stores string.
        static const wxChar* enum_prop_labels[] = { wxT("One Item"),
            wxT("Another Item"), wxT("One More"), wxT("This Is Last"), NULL };

        // This value array would be optional if values matched string indexes
        static long enum_prop_values[] = { 40, 80, 120, 160 };

        // note that the initial value (the last argument) is the actual value,
        // not index or anything like that. Thus, our value selects "Another Item".
        //
        // 0 before value is number of items. If it is 0, like in our example,
        // number of items is calculated, and this requires that the string pointer
        // array is terminated with NULL.
        pg->Append ( wxEnumProperty(wxT("EnumProperty"),wxPG_LABEL,
            enum_prop_labels, enum_prop_values, 0, 80 ) );

    \endcode

    An alternative is to use wxPGConstants class which manages dynamic arrays of strings
    and integers. As of 1.0.0 rc1 wxEnumProperty stores manages arrays given to it,
    including wxPGConstants.

    \code

        // Use basic table from our previous example
        // Can also set/add wxArrayStrings and wxArrayInts directly
        wxPGConstants constants( enum_prop_labels, enum_prop_values );

        // Add extra items
        constants.Add ( wxT("Look, it continues"), 200 );
        constants.Add ( wxT("Even More"), 240 );
        constants.Add ( wxT("And More"), 280 );
        constants.Add ( wxT("True End of the List"), 320 );

        pg->Append ( wxEnumProperty(wxT("EnumProperty2"),
                                    wxPG_LABEL,
                                    constants,
                                    240) );

    \endcode

    You can also get reference to wxEnumProperty's list of choices using
    GetPropertyChoices. This can them be modified or given to further properties
    (in fast and effective manner). There is also AddPropertyChoice which is
    recommended way to append a choice for aproperty.

    \code

        // Continued from our previous example...
        wxPGConstants& choices = pg->GetPropertyChoices(wxT("EnumProperty2"));
        pg->Append( wxEnumProperty(wxT("EnumProperty3"),
                                   wxPG_LABEL,
                                   choices) );

        // This will affect both EnumProperty2 and EnumProperty3 since
        // they both use the same list of choices.
        choices.Add(wxT("Test Item"),360);

    \endcode

    If you want to create your enum properties with simple (label,name,value)
    constructor, then you need to create a new property class using one of the
    supplied macro pairs. See \ref newprops for details.

    wxFlagsProperty is similar:

    \code

        static const wxChar* flags_prop_labels[] = { wxT("wxICONIZE"), 
            wxT("wxCAPTION"), wxT("wxMINIMIZE_BOX"), wxT("wxMAXIMIZE_BOX"), NULL };

        // this value array would be optional if values matched string indexes
        static long flags_prop_values[] = { wxICONIZE, wxCAPTION, wxMINIMIZE_BOX, wxMAXIMIZE_BOX };

        pg->Append( wxFlagsProperty(wxT("FlagsProperty"),
                                    wxPG_LABEL,
                                    flags_prop_labels,
                                    flags_prop_values,
                                    0,
                                    GetWindowStyle()) );

    \endcode

    wxFlagsProperty can use wxPGConstants just the same way as wxEnumProperty
    (and also custom property classes can be created), <b>but currently its
    list of items cannot be modified after it has been created</b> (so please no
    GetPropertyChoices or AddPropertyChoice calls).


    \section advprops Advanced Properties

      This section descbribes the use of less often needed property classes.
    To use them, you need to include <wx/propgrid/advprops.h>.

    \code

    // Necessary extra header file