diff --git a/docs/doxygen/overviews/xrc_format.h b/docs/doxygen/overviews/xrc_format.h index ef77421733..f2ebf4e64c 100644 --- a/docs/doxygen/overviews/xrc_format.h +++ b/docs/doxygen/overviews/xrc_format.h @@ -559,7 +559,7 @@ pseudo-class. @beginTable @hdr3col{property, type, description} @row3col{label, @ref overview_xrcformat_type_text, - Page label (required).} + Page label (default: empty).} @row3col{bitmap, @ref overview_xrcformat_type_bitmap, Bitmap shown alongside the label (default: none).} @row3col{selected, @ref overview_xrcformat_type_bool, @@ -620,7 +620,7 @@ to use it. @row3col{default, @ref overview_xrcformat_type_bool, Should this button be the default button in dialog (default: 0)?} @row3col{bitmap, @ref overview_xrcformat_type_bitmap, - Bitmap to show on the button (required).} + Bitmap to show on the button (default: none).} @row3col{selected, @ref overview_xrcformat_type_bitmap, Bitmap to show when the button is selected (default: none, same as @c bitmap).} @row3col{focus, @ref overview_xrcformat_type_bitmap, @@ -652,7 +652,7 @@ pseudo-class. @c ownerdrawnitem objects have the following properties: @beginTable @hdr3col{property, type, description} @row3col{text, @ref overview_xrcformat_type_text, - Item's label (required).} + Item's label (default: empty).} @row3col{bitmap, @ref overview_xrcformat_type_bitmap, Item's bitmap (default: no bitmap).} @endTable @@ -678,7 +678,7 @@ Example: @beginTable @hdr3col{property, type, description} @row3col{bitmap, @ref overview_xrcformat_type_bitmap, - Label to display on the button (required).} + Label to display on the button (default: none).} @row3col{checked, @ref overview_xrcformat_type_bool, Should the button be checked/pressed initially (default: 0)?} @endTable @@ -787,7 +787,7 @@ its @c notebookpage). @beginTable @hdr3col{property, type, description} @row3col{label, @ref overview_xrcformat_type_text, - Sheet page's title (required).} + Sheet page's title (default: empty).} @row3col{bitmap, @ref overview_xrcformat_type_bitmap, Bitmap shown alongside the label (default: none, mutually exclusive with @c image).} @row3col{image, integer, @@ -811,7 +811,7 @@ concatenated into a single string using a new line character between them @hdr3col{property, type, description} @row3col{label, @ref overview_xrcformat_type_text, First line of text on the button, typically the label of an action that - will be made when the button is pressed (required). } + will be made when the button is pressed (default: empty). } @row3col{note, @ref overview_xrcformat_type_text, Second line of text describing the action performed when the button is pressed (default: none). } @endTable @@ -822,7 +822,7 @@ concatenated into a single string using a new line character between them @beginTable @hdr3col{property, type, description} @row3col{label, @ref overview_xrcformat_type_text, - Label to use for the collapsible section (required).} + Label to use for the collapsible section (default: empty).} @row3col{collapsed, @ref overview_xrcformat_type_bool, Should the pane be collapsed initially (default: 0)?} @endTable @@ -914,7 +914,7 @@ objects. If sizer child is used, it sets @row3col{value, @ref overview_xrcformat_type_string, Initial value of the control (default: empty).} @row3col{message, @ref overview_xrcformat_type_text, - Message shown to the user in wxDirDialog shown by the control (required).} + Message shown to the user in wxDirDialog shown by the control (default: empty).} @endTable @@ -968,7 +968,7 @@ Example: @row3col{value, @ref overview_xrcformat_type_string, Initial value of the control (default: empty).} @row3col{message, @ref overview_xrcformat_type_text, - Message shown to the user in wxDirDialog shown by the control (required).} + Message shown to the user in wxDirDialog shown by the control (default: empty).} @row3col{wildcard, @ref overview_xrcformat_type_string, Sets the wildcard, which can contain multiple file types, for example: "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" @@ -1056,9 +1056,9 @@ page. @beginTable @hdr3col{property, type, description} @row3col{label, @ref overview_xrcformat_type_text, - Label to display on the control (required).} + Label to display on the control (default: empty).} @row3col{url, @ref overview_xrcformat_type_url, - URL to open when the link is clicked (required).} + URL to open when the link is clicked (default: empty).} @endTable @@ -1107,7 +1107,7 @@ its @c notebookpage). @beginTable @hdr3col{property, type, description} @row3col{label, @ref overview_xrcformat_type_text, - Sheet page's title (required).} + Sheet page's title (default: empty).} @row3col{bitmap, @ref overview_xrcformat_type_bitmap, Bitmap shown alongside the label (default: none, mutually exclusive with @c image).} @row3col{image, integer, @@ -1338,7 +1338,7 @@ pseudo-class. @beginTable @hdr3col{property, type, description} @row3col{label, @ref overview_xrcformat_type_text, - Page's title (required).} + Page's title (default: empty).} @row3col{bitmap, @ref overview_xrcformat_type_bitmap, Bitmap shown alongside the label (default: none, mutually exclusive with @c image).} @@ -1415,7 +1415,7 @@ pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its @beginTable @hdr3col{property, type, description} @row3col{label, @ref overview_xrcformat_type_text, - Sheet page's title (required).} + Sheet page's title (default: empty).} @row3col{bitmap, @ref overview_xrcformat_type_bitmap, Bitmap shown alongside the label (default: none).} @row3col{selected, @ref overview_xrcformat_type_bool, @@ -1430,7 +1430,7 @@ Each @c propertysheetpage has exactly one non-toplevel window as its child. @beginTable @hdr3col{property, type, description} @row3col{label, @ref overview_xrcformat_type_text, - Label shown on the radio button (required).} + Label shown on the radio button (default: empty).} @row3col{value, @ref overview_xrcformat_type_bool, Initial value of the control (default: 0).} @endTable @@ -1557,9 +1557,9 @@ objects have the following properties: @row3col{disabled, @ref overview_xrcformat_type_bool, Whether the button should be disabled (default: false).} @row3col{label, @ref overview_xrcformat_type_text, - Item's label (required).} + Item's label (default: empty).} @row3col{bitmap, @ref overview_xrcformat_type_bitmap, - Item's bitmap (required).} + Item's bitmap (default: none).} @row3col{small-bitmap, @ref overview_xrcformat_type_bitmap, Small bitmap (default: none).} @row3col{disabled-bitmap, @ref overview_xrcformat_type_bitmap, @@ -1853,7 +1853,7 @@ No additional properties. @beginTable @hdr3col{property, type, description} @row3col{label, @ref overview_xrcformat_type_text, - Label to display on the button (required).} + Label to display on the button (default: empty).} @row3col{checked, @ref overview_xrcformat_type_bool, Should the button be checked/pressed initially (default: 0)?} @endTable @@ -1891,7 +1891,7 @@ properties: @beginTable @hdr3col{property, type, description} @row3col{bitmap, @ref overview_xrcformat_type_bitmap, - Tool's bitmap (required).} + Tool's bitmap (default: empty).} @row3col{bitmap2, @ref overview_xrcformat_type_bitmap, Bitmap for disabled tool (default: derived from @c bitmap).} @row3col{label, @ref overview_xrcformat_type_text, @@ -1979,7 +1979,7 @@ pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its @beginTable @hdr3col{property, type, description} @row3col{label, @ref overview_xrcformat_type_text, - Sheet page's title (required).} + Sheet page's title (default: empty).} @row3col{bitmap, @ref overview_xrcformat_type_bitmap, Bitmap shown alongside the label (default: none, mutually exclusive with @c image).} @@ -2020,9 +2020,9 @@ pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its @beginTable @hdr3col{property, type, description} @row3col{depth, integer, - Page's depth in the labels tree (required; see below).} + Page's depth in the labels tree (default: 0; see below).} @row3col{label, @ref overview_xrcformat_type_text, - Sheet page's title (required).} + Sheet page's title (default: empty).} @row3col{bitmap, @ref overview_xrcformat_type_bitmap, Bitmap shown alongside the label (default: none, mutually exclusive with @c image).} @row3col{image, integer, @@ -2312,7 +2312,7 @@ class-specific properties. All classes support the following properties: @beginTable @hdr3col{property, type, description} @row3col{orient, @ref overview_xrcformat_type_style, - Sizer orientation, "wxHORIZONTAL" or "wxVERTICAL" (required).} + Sizer orientation, "wxHORIZONTAL" or "wxVERTICAL" (default: wxHORIZONTAL).} @row3col{flag, @ref overview_xrcformat_type_style, wxWrapSizer flags (default: 0).} @endTable diff --git a/misc/schema/xrc_schema.rnc b/misc/schema/xrc_schema.rnc index cf6f68a656..cb2170ed96 100644 --- a/misc/schema/xrc_schema.rnc +++ b/misc/schema/xrc_schema.rnc @@ -76,11 +76,15 @@ start = # # (2) The other 'platform'-related issue is that it messes up cardinality of # properties elements. Properties can only be specified once, so the two forms -# for describing properties are +# for describing properties would be # # 1. element size {_, t_size }? # optional property # 2. element size {_, t_size } # required property # +# (Fortunately, all XRC properties are optional, se the second case is a +# non-issue and can be safely ignored. It is nevertheless briefly mentioned +# below for explanatory purposes.) +# # But this is problematic with 'platform', because it's reasonable (and, # indeed, done in the wild) to set properties differently for different # platforms: @@ -111,14 +115,24 @@ start = # # But this is verbose and unreadable with the amount of properties present in # the schema. Instead, we use the more-forbidding version and annotate -# properties with 'p' annotation (for "property") that has either 'r' -# (required) or 'o' (optional) value: +# properties with 'p' annotation (for "property") to mark these uses of * as +# special and enable post-processing of the schema. # -# [xrc:p="o"] element checked { t_bool }* # optional -# [xrc:p="r"] element label { t_text }+ # required +# The value of the annotation is normally just "o" (for "optional" -- remember +# that there are no required properties) to indicate optional properties. +# +# Since we have the annotation anyway, we take advantage of it to indicate +# properties that are strictly speaking optional, but should almost always be +# specified, even though they don't _have_ to be. A typical example would be +# wxStaticText's label: it very rarely makes sense to omit it, but usually +# doesn't. Such properties are indicated with the "important" value of the +# annotation: +# +# [xrc:p="o"] element checked { t_bool }* # optional +# [xrc:p="important"] element label { t_text }* # should be provided # # This makes it possible to implement tools that translate this schema into a -# variant that use [B]. +# variant that uses [B]. # toplevelObjectNode = (objectRef | builtinToplevelClasses | customClasses) @@ -352,8 +366,9 @@ anyXMLContent = # # [xrc:p] marks properties, with two possible values: # -# [xrc:p="r"] for required properties -# [xrc:p="o"] for optional properties +# [xrc:p="o"] for normal/optional properties +# [xrc:p="important"] for important properties that +# should almost always be set # @@ -503,7 +518,7 @@ wxAuiNotebook = wxAuiNotebook_notebookpage = element object { attribute class { "notebookpage" } & - [xrc:p="r"] element label {_, t_text }+ & + [xrc:p="important"] element label {_, t_text }* & [xrc:p="o"] element bitmap {_, t_bitmap }* & [xrc:p="o"] element selected {_, t_bool }* & windowNode @@ -534,7 +549,7 @@ wxBitmapButton = stdObjectNodeAttributes & stdWindowProperties & [xrc:p="o"] element default {_, t_bool }* & - [xrc:p="r"] element bitmap {_, t_bitmap }+ & + [xrc:p="important"] element bitmap {_, t_bitmap }* & [xrc:p="o"] element selected {_, t_bitmap }* & [xrc:p="o"] element focus {_, t_bitmap }* & [xrc:p="o"] element disabled {_, t_bitmap }* & @@ -556,7 +571,7 @@ wxBitmapComboBox_ownerdrawnitem = element object { attribute class { "ownerdrawnitem" } & platform & - [xrc:p="r"] element text {_, t_text }+ & + [xrc:p="important"] element text {_, t_text }* & [xrc:p="o"] element bitmap {_, t_bitmap }* } @@ -566,7 +581,7 @@ wxBitmapToggleButton = attribute class { "wxBitmapToggleButton" } & stdObjectNodeAttributes & stdWindowProperties & - [xrc:p="r"] element bitmap {_, t_bitmap }+ & + [xrc:p="important"] element bitmap {_, t_bitmap }* & [xrc:p="o"] element checked {_, t_bool }* } @@ -596,7 +611,7 @@ wxCheckBox = attribute class { "wxCheckBox" } & stdObjectNodeAttributes & stdWindowProperties & - [xrc:p="o"] element label {_, t_text }* & + [xrc:p="important"] element label {_, t_text }* & [xrc:p="o"] element checked {_, t_bool }* } @@ -642,7 +657,7 @@ wxChoicebook_choicebookpage = element object { attribute class { "choicebookpage" } & platform & - [xrc:p="r"] element label {_, t_text }+ & + [xrc:p="important"] element label {_, t_text }* & [xrc:p="o"]( element bitmap {_, t_bitmap } | element image {_, t_integer } @@ -657,7 +672,7 @@ wxCommandLinkButton = attribute class { "wxCommandLinkButton" } & stdObjectNodeAttributes & stdWindowProperties & - [xrc:p="r"] element label {_, t_text }+ & + [xrc:p="important"] element label {_, t_text }* & [xrc:p="o"] element note {_, t_text }* } @@ -667,7 +682,7 @@ wxCollapsiblePane = attribute class { "wxCollapsiblePane" } & stdObjectNodeAttributes & stdWindowProperties & - [xrc:p="r"] element label {_, t_text }+ & + [xrc:p="important"] element label {_, t_text }* & [xrc:p="o"] element collapsed {_, t_bool }* & (wxCollapsiblePane_panewindow | objectRef)? } @@ -738,7 +753,7 @@ wxDirPickerCtrl = stdObjectNodeAttributes & stdWindowProperties & [xrc:p="o"] element value {_, t_string }* & - [xrc:p="r"] element message {_, t_text}+ + [xrc:p="important"] element message {_, t_text}* } @@ -772,7 +787,7 @@ wxFilePickerCtrl = stdObjectNodeAttributes & stdWindowProperties & [xrc:p="o"] element value {_, t_string }* & - [xrc:p="r"] element message {_, t_text }+ & + [xrc:p="important"] element message {_, t_text }* & [xrc:p="o"] element wildcard {_, t_string }* } @@ -847,8 +862,8 @@ wxHyperlinkCtrl = attribute class { "wxHyperlinkCtrl" } & stdObjectNodeAttributes & stdWindowProperties & - [xrc:p="r"] element label {_, t_text }+ & - [xrc:p="r"] element url {_, t_url }+ + [xrc:p="important"] element label {_, t_text }* & + [xrc:p="important"] element url {_, t_url }* } @@ -877,7 +892,7 @@ wxListbook = wxListbook_listbookpage = element object { attribute class { "listbookpage" } & - [xrc:p="r"] element label {_, t_text }+ & + [xrc:p="important"] element label {_, t_text }* & [xrc:p="o"]( element bitmap {_, t_bitmap } | element image {_, t_integer } @@ -1009,7 +1024,7 @@ wxNotebook_notebookpage = element object { attribute class { "notebookpage" } & platform & - [xrc:p="r"] element label {_, t_text }+ & + [xrc:p="important"] element label {_, t_text }* & ( element bitmap {_, t_bitmap } | element image {_, t_integer } @@ -1059,7 +1074,7 @@ wxPropertySheetDialog_propertysheetpage = element object { attribute class { "propertysheetpage" } & platform & - [xrc:p="r"] element label {_, t_text }+ & + [xrc:p="important"] element label {_, t_text }* & [xrc:p="o"] element bitmap {_, t_bitmap }* & [xrc:p="o"] element selected {_, t_bool }* & windowNode @@ -1071,7 +1086,7 @@ wxRadioButton = attribute class { "wxRadioButton" } & stdObjectNodeAttributes & stdWindowProperties & - [xrc:p="r"] element label {_, t_text }+ & + [xrc:p="important"] element label {_, t_text }* & [xrc:p="o"] element value {_, t_bool }* } @@ -1081,7 +1096,7 @@ wxRadioBox = attribute class { "wxRadioBox" } & stdObjectNodeAttributes & stdWindowProperties & - [xrc:p="o"] element label {_, t_text }* & + [xrc:p="important"] element label {_, t_text }* & [xrc:p="o"] element dimension {_, t_integer }* & [xrc:p="o"] element selection {_, t_integer }* & element content { @@ -1121,8 +1136,8 @@ wxRibbonButtonBar_button = stdObjectNodeAttributes & [xrc:p="o"] element hybrid {_, t_bool }* & [xrc:p="o"] element disabled {_, t_bool }* & - [xrc:p="r"] element label {_, t_text }+ & - [xrc:p="r"] element bitmap {_, t_bitmap }+ & + [xrc:p="important"] element label {_, t_text }* & + [xrc:p="important"] element bitmap {_, t_bitmap }* & [xrc:p="o"] element small-bitmap {_, t_bitmap }* & [xrc:p="o"] element disabled-bitmap {_, t_bitmap }* & [xrc:p="o"] element small-disabled-bitmap {_, t_bitmap }* & @@ -1311,7 +1326,7 @@ wxStaticBox = attribute class { "wxStaticBox" } & stdObjectNodeAttributes & stdWindowProperties & - [xrc:p="o"] element label {_, t_text }* + [xrc:p="important"] element label {_, t_text }* } @@ -1328,7 +1343,7 @@ wxStaticText = attribute class { "wxStaticText" } & stdObjectNodeAttributes & stdWindowProperties & - [xrc:p="o"] element label {_, t_text }* & + [xrc:p="important"] element label {_, t_text }* & [xrc:p="o"] element wrap {_, t_dimension }* } @@ -1356,7 +1371,7 @@ wxToggleButton = attribute class { "wxToggleButton" } & stdObjectNodeAttributes & stdWindowProperties & - [xrc:p="r"] element label {_, t_text }+ & + [xrc:p="important"] element label {_, t_text }* & [xrc:p="o"] element checked {_, t_bool }* } @@ -1383,7 +1398,7 @@ wxToolBar_tool = element object { attribute class { "tool" } & stdObjectNodeAttributes & - [xrc:p="r"] element bitmap {_, t_bitmap }+ & + [xrc:p="important"] element bitmap {_, t_bitmap }* & [xrc:p="o"] element bitmap2 {_, t_bitmap }* & [xrc:p="o"] element label {_, t_text }* & [xrc:p="o"] element tooltip {_, t_text }* & @@ -1411,7 +1426,7 @@ wxToolbook_toolbookpage = element object { attribute class { "toolbookpage" } & platform & - [xrc:p="r"] element label {_, t_text }+ & + [xrc:p="important"] element label {_, t_text }* & [xrc:p="o"]( element bitmap {_, t_bitmap } | element image {_, t_integer } @@ -1443,8 +1458,8 @@ wxTreebook_treebookpage = element object { attribute class { "treebookpage" } & platform & - [xrc:p="r"] element depth {_, t_integer }+ & - [xrc:p="r"] element label {_, t_text }+ & + [xrc:p="important"] element depth {_, t_integer }* & + [xrc:p="important"] element label {_, t_text }* & [xrc:p="o"]( element bitmap {_, t_bitmap } | element image {_, t_integer } @@ -1519,7 +1534,7 @@ wxStaticBoxSizer = attribute class { "wxStaticBoxSizer" } & stdObjectNodeAttributes & [xrc:p="o"] element minsize {_, t_size }* & - [xrc:p="o"] element label {_, t_text }* & + [xrc:p="important"] element label {_, t_text }* & [xrc:p="o"] element orient {_, ("wxHORIZONTAL" | "wxVERTICAL") }* & (wxSizer_item | objectRef)* } @@ -1575,7 +1590,7 @@ wxWrapSizer = attribute class { "wxWrapSizer" } & stdObjectNodeAttributes & [xrc:p="o"] element minsize {_, t_size }* & - [xrc:p="r"] element orient {_, ("wxHORIZONTAL" | "wxVERTICAL") }+ & + [xrc:p="important"] element orient {_, ("wxHORIZONTAL" | "wxVERTICAL") }* & [xrc:p="o"] element flag {_, t_style }* & (wxSizer_item | objectRef)* }