From 8c586b6ff537b2868484f9b001b50e5da4f5f14e Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Sun, 12 Nov 2023 20:52:19 +0100 Subject: [PATCH] Add minimal documentation of wxPropertyGrid XRC format Not everything is documented yet, mostly because it's not really easy to find out what "everything" actually is. --- docs/doxygen/overviews/propgrid.h | 5 +- docs/doxygen/overviews/xrc_format.h | 135 ++++++++++++++++++++++++++++ 2 files changed, 137 insertions(+), 3 deletions(-) diff --git a/docs/doxygen/overviews/propgrid.h b/docs/doxygen/overviews/propgrid.h index d9034a4a62..5d6aaa8b84 100644 --- a/docs/doxygen/overviews/propgrid.h +++ b/docs/doxygen/overviews/propgrid.h @@ -578,9 +578,8 @@ in an arbitrary list of wxVariants. @subsection propgrid_fromfile Loading Population from a Text-based Storage Class wxPropertyGridPopulator may be helpful when writing code that -loads properties from a text-source. In fact, the wxPropertyGrid xrc-handler -(which may not be currently included in wxWidgets, but probably will be in -near future) uses it. +loads properties from a text-source. It is used by wxPropertyGrid XRC handler, +for example. @subsection editablestate Saving and Restoring User-Editable State diff --git a/docs/doxygen/overviews/xrc_format.h b/docs/doxygen/overviews/xrc_format.h index acbdfa6724..7d6c0e2257 100644 --- a/docs/doxygen/overviews/xrc_format.h +++ b/docs/doxygen/overviews/xrc_format.h @@ -298,6 +298,13 @@ DPI-dependent scaling, i.e. the format is just and @c x and @c y are just integers which are not interpreted in any way. +@subsection overview_xrcformat_type_percent Integer or percent + +This is a value which can be either a simple (unsigned) integer or a percent, +specified as `N%`, with a literal percent sign, of some other implicitly +specified length. + + @subsection overview_xrcformat_type_text Text String properties use several escape sequences that are translated according to @@ -1737,6 +1744,134 @@ wxPanel may have optional children: either exactly one objects. +@subsubsection xrc_wxpropertygrid wxPropertyGrid + +@beginTable +@hdr3col{property, type, description} +@row3col{virtualwidth, @ref overview_xrcformat_type_dimension, + Optional width passed to wxPropertyGrid::SetVirtualWidth().} +@endTable + +A wxPropertyGrid may have @ref xrc_wxpropertygridproperty child objects. + +Example: +@code + + + + Now And Then + + + + 2023 + + +@endcode + +Notice that wxPropertyGrid support in XRC is available in wxWidgets 3.3.0 and +later only and you need to explicitly register its handler using +@code + #include + + AddHandler(new wxPropertyGridXmlHandler); +@endcode +to use it. + + +@subsubsection xrc_wxpropertygridmanager wxPropertyGridManager + +@beginTable +@hdr3col{property, type, description} +@row3col{virtualwidth, @ref overview_xrcformat_type_dimension, + Optional width passed to wxPropertyGrid::SetVirtualWidth().} +@endTable + +A wxPropertyGridManager contains one or more `page` elements each of which in +turn contains one of more @ref xrc_wxpropertygridproperty child objects. + +Page elements may also have the following attributes: +@beginTable +@hdr3col{property, type, description} +@row3col{label, @ref overview_xrcformat_type_text, + Label used for the page.} +@row3col{columns, integer, + Optional column count passed to wxPropertyGridPageState::SetColumnCount().} +@row3col{splitterpos, @ref overview_xrcformat_type_percent, + Optional splitter position passed to wxPropertyGridPageState::DoSetSplitter(). + The `pos` argument of this function may be specified as `index` attribute + of this element and defaults to 0 if not given.} +@row3col{choices, strings, + Space-separated list of double-quoted strings which can be used as choices + in a wxEnumProperty of this wxPropertyGridManager object by using the + `id` attribute of this element there.} +@endTable + +Example: +@code + + + + + Now And Then + + + + 2023 + + + + + "1" "2" "3" "4" "5" + + + 87 + + + + 4 + @stars + + + +@endcode + +Notice that wxPropertyGrid support in XRC is available in wxWidgets 3.3.0 and +later only and you need to explicitly register its handler using +@code + #include + + AddHandler(new wxPropertyGridXmlHandler); +@endcode +to use it. + + +@subsubsection xrc_wxpropertygridproperty wxPropertyGridProperty + +@beginTable +@hdr3col{property, type, description} +@row3col{label, @ref overview_xrcformat_type_text, + Property label appearing in the property grid.} +@row3col{value, @ref overview_xrcformat_type_string, + Initial property value.} +@row3col{flags, @ref overview_xrcformat_type_style, + Combination of wxPGPropertyFlags values without the leading `wxPG_PROP_` + prefix. Only "COLLAPSED", "DISABLED", "HIDDEN" and "NOEDITOR" are currently + allowed. (default: 0).} +@row3col{tip, @ref overview_xrcformat_type_text, + Optional help string.} +@row3col{expanded, @ref overview_xrcformat_type_bool, + For a property with children, may be used to specify whether it should be + expanded by default.} +@row3col{choices, @ref overview_xrcformat_type_string, + Space-separated string containing the possible choices for the properties + using them, e.g. wxFlagsProperty or wxEnumProperty.} +@endTable + +These elements define individual rows of @ref xrc_wxpropertygrid or @ref +xrc_wxpropertygridmanager. Notice that they may be nested: a property with the +class "wxPropertyCategory" will normally contain other properties inside it. + + @subsubsection xrc_wxpropertysheetdialog wxPropertySheetDialog @beginTable