AuroraMiddleware/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

XRC spec: say that all properties are optional.

Browse Source 
Provide defaults for all properties in the spec.  In XRC schema, make
all properties optional.  The previously required ones are annotated as
"important" (read: should be set unless you know what you're doing), but
aren't enforced.

The code already behaved like this, so this just synchronizes the
specification with the reality.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@75043 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Václav Slavík 2013-10-18 15:00:06 +00:00
parent 380aa9533e
commit 1662725c75
2 changed files with 74 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
docs/doxygen/overviews/xrc_format.h
View File

@ -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

87
misc/schema/xrc_schema.rnc
View File

@ -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)*
}