From be42eeb0c3e620e642e963f9bf3b29d0cbcd561e Mon Sep 17 00:00:00 2001 From: =?utf8?q?V=C3=A1clav=20Slav=C3=ADk?= Date: Wed, 1 Oct 2008 10:25:45 +0000 Subject: [PATCH] finished XRC format specification: added docs for all standard controls git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@56006 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/doxygen/overviews/xrc_format.h | 1035 +++++++++++++++++++++++++-- docs/tech/index.txt | 2 +- docs/tech/tn0014.txt | 548 -------------- 3 files changed, 979 insertions(+), 606 deletions(-) delete mode 100644 docs/tech/tn0014.txt diff --git a/docs/doxygen/overviews/xrc_format.h b/docs/doxygen/overviews/xrc_format.h index 18931c53af..5152171ac3 100644 --- a/docs/doxygen/overviews/xrc_format.h +++ b/docs/doxygen/overviews/xrc_format.h @@ -334,6 +334,19 @@ Like @ref xrc_format_type_text, but the text is never translated and @c translate attribute cannot be used. +@subsection xrc_format_type_string URL + +An unformatted string. Unlike with @ref xrc_format_type_text, no escaping +or translations are done. + + +@subsection xrc_format_type_url URL + +Any URL accepted by wxFileSystem (typically relative to XRC file's location, +but can be absolute too). Unlike with @ref xrc_format_type_text, no escaping +or translations are done. + + @subsection xrc_format_type_bitmap Bitmap Bitmap properties contain specification of a single bitmap or icon. In the most @@ -455,7 +468,7 @@ from properties lists below. @beginTable @hdr3col{property, type, description} -@row3col{position, @ref xrc_format_type_pos, +@row3col{pos, @ref xrc_format_type_pos, Initial position of the window (default: wxDefaultPosition).} @row3col{size, @ref xrc_format_type_size, Initial size of the window (default: wxDefaultSize).} @@ -489,170 +502,1078 @@ All of these properties are optional. @subsection xrc_format_controls Supported controls +This section lists all controls supported by default. For each control, its +control-specific properties are listed. If the control can have child objects, +it is documented there too; unless said otherwise, XRC elements for these +controls cannot have children. + @subsubsection xrc_wxanimationctrl wxAnimationCtrl -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{animation, @ref xrc_format_type_url, + Animation file to load into the control (required).} +@endTable + @subsubsection xrc_wxbitmapbutton wxBitmapButton -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{default, @ref xrc_format_type_bool, + Should this button be the default button in dialog (default: 0)?} +@row3col{bitmap, @ref xrc_format_type_bitmap, + Bitmap to show on the button (required).} +@row3col{selected, @ref xrc_format_type_bitmap, + Bitmap to show when the button is selected (default: none, same as @c bitmap).} +@row3col{focus, @ref xrc_format_type_bitmap, + Bitmap to show when the button has focus (default: none, same as @c bitmap).} +@row3col{disabled, @ref xrc_format_type_bitmap, + Bitmap to show when the button is disabled (default: none, same as @c bitmap).} +@row3col{hover, @ref xrc_format_type_bitmap, + Bitmap to show when mouse cursor hovers above the bitmap (default: none, same as @c bitmap).} +@endTable + @subsubsection xrc_wxbitmapcombobox wxBitmapComboBox -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{selection, integer, + Index of the initially selected item or -1 for no selection (default: -1).} +@row3col{value, @ref xrc_format_type_string, + Initial value in the control (doesn't have to be one of @ content values; + default: empty).} +@endTable + +If both @c value and @c selection are specified and @c selection is not -1, +then @c selection takes precedence. + +A wxBitmapComboBox can have one or more child objects of the @c ownerdrawnitem +pseudo-class. @c ownerdrawnitem objects have the following properties: + +@beginTable +@hdr3col{property, type, description} +@row3col{text, @ref xrc_format_type_text, + Item's label (required).} +@row3col{bitmap, @ref xrc_format_type_bitmap, + Item's bitmap (default: no bitmap).} +@endTable + +Example: +@code + + 1 + + Foo + foo.png + + + Bar + bar.png + + +@endcode + @subsubsection xrc_wxbutton wxButton -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{label, @ref xrc_format_type_text, + Label to display on the button (required).} +@row3col{default, @ref xrc_format_type_bool, + Should this button be the default button in dialog (default: 0)?} +@endTable + @subsubsection xrc_wxcalendarctrl wxCalendarCtrl -FIXME + +No additional properties. + @subsubsection xrc_wxcheckbox wxCheckBox -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{label, @ref xrc_format_type_text, + Label to use for the checkbox (required).} +@row3col{checked, @ref xrc_format_type_bool, + Should the checkbox be checked initially (default: 0)?} +@endTable + @subsubsection xrc_wxchecklistbox wxCheckListBox -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{content, , + Content of the control; this property has any number of @c \ XML + elements as its children, with the items text as their text values + (default: empty).} +@endTable + +The @c \ elements have listbox items' labels as their text values. They +can also have optional @c checked XML attribute -- if set to "1", the value is +initially checked. + +Example: +@code + + + Download library + Compile samples + Skim docs + Finish project + Wash car + + +@endcode + @subsubsection xrc_wxchoice wxChoice -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{selection, integer, + Index of the initially selected item or -1 for no selection (default: -1).} +@row3col{content, , + Content of the control; this property has any number of @c \ XML + elements as its children, with the items text as their text values + (default: empty).} +@endTable + +Example: +@code + + + See + Hear + Feel + Smell + Taste + The Sixth Sense! + + +@endcode + @subsubsection xrc_wxchoicebook wxChoicebook -FIXME + +No additional properties. + +A choicebook can have one or more child objects of the @c choicebookpage +pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its +@c notebookpage). @c choicebookpage objects have the following properties: + +@beginTable +@hdr3col{property, type, description} +@row3col{label, @ref xrc_format_type_text, + Sheet page's title (required).} +@row3col{bitmap, @ref xrc_format_type_bitmap, + Bitmap shown alongside the label (default: none).} +@row3col{selected, @ref xrc_format_type_bool, + Is the page selected initially (only one page can be selected; default: 0)?} +@endTable + +Each @c choicebookpage has exactly one non-toplevel window as its child. + @subsubsection xrc_wxcollapsiblepane wxCollapsiblePane -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{label, @ref xrc_format_type_text, + Label to use for the collapsible section (required).} +@row3col{collapsed, @ref xrc_format_type_bool, + Should the pane be collapsed initially (default: 0)?} +@endTable + +wxCollapsiblePane may contain single optional child object of the @c panewindow +pseudo-class type. @c panewindow itself must contain exactly one child that +is a @ref xrc_format_sizers "sizer" or a non-toplevel window +object. + @subsubsection xrc_wxcolourpickerctrl wxColourPickerCtrl -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{value, @ref xrc_format_type_colour, + Initial value of the control (default: wxBLACK).} +@endTable + @subsubsection xrc_wxcombobox wxComboBox -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{selection, integer, + Index of the initially selected item or -1 for no selection (default: not used).} +@row3col{content, , + Content of the control; this property has any number of @c \ XML + elements as its children, with the items text as their text values + (default: empty).} +@row3col{value, @ref xrc_format_type_string, + Initial value in the control (doesn't have to be one of @ content values; + default: empty).} +@endTable + +If both @c value and @c selection are specified and @c selection is not -1, +then @c selection takes precedence. + +Example: +@code + + + nedit + + vim + emacs + notepad.exe + bbedit + + +@endcode @subsubsection xrc_wxdatepickerctrl wxDatePickerCtrl -FIXME + +No additional properties. + @subsubsection xrc_wxdialog wxDialog -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{title, @ref xrc_format_type_text, + Dialog's title (default: empty).} +@row3col{icon, @ref xrc_format_type_bitmap, + Dialog's icon (default: not used).} +@row3col{centered, @ref xrc_format_type_bool, + Whether the dialog should be centered on the screen (default: 0).} +@endTable + +wxDialog may have optional children: either exactly one +@ref xrc_format_sizers "sizer" child or any number of non-toplevel window +objects. If sizer child is used, it sets +@ref wxSizer::SetSizeHints() "size hints" too. @subsubsection xrc_wxdirpickerctrl wxDirPickerCtrl -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{value, @ref xrc_format_type_string, + Initial value of the control (default: empty).} +@row3col{message, @ref xrc_format_type_text, + Message shown to the user in wxDirDialog shown by the control (required).} +@endTable + @subsubsection xrc_wxfilepickerctrl wxFilePickerCtrl -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{value, @ref xrc_format_type_string, + Initial value of the control (default: empty).} +@row3col{message, @ref xrc_format_type_text, + Message shown to the user in wxDirDialog shown by the control (required).} +@row3col{wildcard, @ref xrc_format_type_string, + Message shown to the user in wxDirDialog shown by the control (required).} +@endTable + @subsubsection xrc_wxfontpickerctrl wxFontPickerCtrl -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{value, @ref xrc_format_type_font, + Initial value of the control (default: wxNORMAL_FONT).} +@endTable @subsubsection xrc_wxfrane wxFrame -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{title, @ref xrc_format_type_text, + Frame's title (default: empty).} +@row3col{icon, @ref xrc_format_type_bitmap, + Frame's icon (default: not used).} +@row3col{centered, @ref xrc_format_type_bool, + Whether the frame should be centered on the screen (default: 0).} +@endTable + +wxFrame may have optional children: either exactly one +@ref xrc_format_sizers "sizer" child or any number of non-toplevel window +objects. If sizer child is used, it sets +@ref wxSizer::SetSizeHints() "size hints" too. + @subsubsection xrc_wxgauge wxGauge -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{range, integer, + Maximum value of the gauge (default: wxGAUGE_DEFAULT_RANGE).} +@row3col{value, integer, + Initial value of the control (default: 0).} +@row3col{shadow, @ref xrc_format_type_dimension, + Rendered shadow size (default: none; ignored by most platforms).} +@row3col{bezel, @ref xrc_format_type_dimension, + Rendered bezel size (default: none; ignored by most platforms).} +@endTable @subsubsection xrc_wxgenericdirctrl wxGenericDirCtrl -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{defaultfolder, @ref xrc_format_type_text, + Initial folder (default: empty).} +@row3col{filter, @ref xrc_format_type_text, + Filter string, using the same syntax as used by wxFileDialog, e.g. + "All files (*.*)|*.*|JPEG files (*.jpg)|*.jpg" (default: empty).} +@row3col{defaultfilter, integer, + Zero-based index of default filter (default: 0).} +@endTable @subsubsection xrc_wxgrid wxGrid -FIXME + +No additional properties. + @subsubsection xrc_wxhtmlwindow wxHtmlWindow -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{url, @ref xrc_format_type_url, + Page to display in the window.} +@row3col{htmlcode, @ref xrc_format_type_text, + HTML markup to display in the window.} +@row3col{borders, @ref xrc_format_type_dimension, + Border around HTML content (default: 0).} +@endTable + +At most one of @c url and @c htmlcode properties may be specified, they are +mutually exclusive. If neither is set, the window is initialized to show empty +page. + @subsubsection xrc_wxhyperlinkctrl wxHyperlinkCtrl -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{label, @ref xrc_format_type_text, + Label to display on the control (required).} +@row3col{url, @ref xrc_format_type_url, + URL to open when the link is clicked (required).} +@endTable + @subsubsection xrc_wxlistbox wxListBox -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{selection, integer, + Index of the initially selected item or -1 for no selection (default: -1).} +@row3col{content, , + Content of the control; this property has any number of @c \ XML + elements as its children, with the items text as their text values + (default: empty).} +@endTable + +Example: +@code + + 250,160 + + + Milk + Pizza + Bread + Orange juice + Paper towels + + +@endcode + @subsubsection xrc_wxlistbook wxListbook -FIXME + +No additional properties. + +A listbook can have one or more child objects of the @c listbookpage +pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its +@c notebookpage). @c listbookpage objects have the following properties: + +@beginTable +@hdr3col{property, type, description} +@row3col{label, @ref xrc_format_type_text, + Sheet page's title (required).} +@row3col{bitmap, @ref xrc_format_type_bitmap, + Bitmap shown alongside the label (default: none).} +@row3col{selected, @ref xrc_format_type_bool, + Is the page selected initially (only one page can be selected; default: 0)?} +@endTable + +Each @c listbookpage has exactly one non-toplevel window as its child. + @subsubsection xrc_wxlistctrl wxListCtrl -FIXME + +No additional properties. + @subsubsection xrc_wxmdiparentframe wxMDIParentFrame -FIXME + +wxMDIParentFrame supports the same properties that @ref xrc_wxfrane does. + +wxMDIParentFrame may have optional children. When used, the child objects +must be of wxMDIChildFrame type. + @subsubsection xrc_wxmdichildframe wxMDIChildFrame -FIXME + +wxMDIChildFrame supports the same properties that @ref xrc_wxfrane and +@ref xrc_wxmdiparentframe do. + +wxMDIChildFrame can only be used as as immediate child of @ref +xrc_wxmdiparentframe. + +wxMDIChildFrame may have optional children: either exactly one +@ref xrc_format_sizers "sizer" child or any number of non-toplevel window +objects. If sizer child is used, it sets +@ref wxSizer::SetSizeHints() "size hints" too. + @subsubsection xrc_wxmenu wxMenu -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{label, @ref xrc_format_type_text, + Menu's label (default: empty, but required for menus other + than popup menus).} +@row3col{help, @ref xrc_format_type_text, + Help shown in statusbar when the menu is selected (only for submenus + of another wxMenu, default: none).} +@row3col{enabled, @ref xrc_format_type_bool, + Is the submenu item enabled (only for submenus of another wxMenu, + default: 1)?} +@endTable + +Note that unlike most controls, wxMenu does @em not have +@ref xrc_format_std_props. + +A menu object can have one or more child objects of the wxMenuItem or wxMenu +classes or @c break or @c separator pseudo-classes. + +The @c separator pseudo-class is used to insert separators into the menu and +has neither properties nor children. Likewise, @c break inserts a break (see +wxMenu::Break()). + +wxMenuItem objects support the following properties: + +@beginTable +@hdr3col{property, type, description} +@row3col{label, @ref xrc_format_type_text, + Item's label (required).} +@row3col{accel, @ref xrc_format_type_text_notrans, + Item's accelerator (default: none).} +@row3col{radio, @ref xrc_format_type_bool, + Item's kind is wxITEM_RADIO (default: 0)?} +@row3col{checkable, @ref xrc_format_type_bool, + Item's kind is wxITEM_CHECK (default: 0)?} +@row3col{bitmap, @ref xrc_format_type_bitmap, + Bitmap to show with the item (default: none).} +@row3col{bitmap2, @ref xrc_format_type_bitmap, + Bitmap for the checked state (wxMSW, if checkable; default: none).} +@row3col{help, @ref xrc_format_type_text, + Help shown in statusbar when the item is selected (default: none).} +@row3col{enabled, @ref xrc_format_type_bool, + Is the item enabled (default: 1)?} +@row3col{checked, @ref xrc_format_type_bool, + Is the item checked initially (default: 0)?} +@endTable + +Example: +@code + + + + + + Ctrl-F + + + + + 1 + + + + ... + ... + + + + + + +@endcode @subsubsection xrc_wxmenubar wxMenuBar -FIXME + +No properties. Note that unlike most controls, wxMenuBar does @em not have +@ref xrc_format_std_props. + +A menubar can have one or more child objects of the @ref xrc_wxmenu "wxMenu" +class. + @subsubsection xrc_wxnotebook wxNotebook -FIXME + +No additional properties. + +A notebook can have one or more child objects of the @c notebookpage +pseudo-class. @c notebookpage objects have the following properties: + +@beginTable +@hdr3col{property, type, description} +@row3col{label, @ref xrc_format_type_text, + Page's title (required).} +@row3col{bitmap, @ref xrc_format_type_bitmap, + Bitmap shown alongside the label (default: none).} +@row3col{selected, @ref xrc_format_type_bool, + Is the page selected initially (only one page can be selected; default: 0)?} +@endTable + +Each @c notebookpage has exactly one non-toplevel window as its child. + +Example: +@code + + + + + + ... + + + + + + ... + + + +@endcode + @subsubsection xrc_wxownerdrawncombobox wxOwnerDrawnComboBox -FIXME + +wxOwnerDrawnComboBox has the same properties as +@ref xrc_wxcombobox "wxComboBox", plus the following additional properties: + +@beginTable +@hdr3col{property, type, description} +@row3col{buttonsize, @ref xrc_format_type_size, + Size of the dropdown button (default: default).} +@endTable + @subsubsection xrc_wxpanel wxPanel -FIXME + +No additional properties. + +wxPanel may have optional children: either exactly one +@ref xrc_format_sizers "sizer" child or any number of non-toplevel window +objects. + @subsubsection xrc_wxpropertysheetdialog wxPropertySheetDialog -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{title, @ref xrc_format_type_text, + Dialog's title (default: empty).} +@row3col{icon, @ref xrc_format_type_bitmap, + Dialog's icon (default: not used).} +@row3col{centered, @ref xrc_format_type_bool, + Whether the dialog should be centered on the screen (default: 0).} +@row3col{buttons, @ref xrc_format_type_style, + Buttons to show, combination of flags accepted by + wxPropertySheetDialog::CreateButtons() (default: 0).} +@endTable + +A sheet dialog can have one or more child objects of the @c propertysheetpage +pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its +@c notebookpage). @c propertysheetpage objects have the following properties: + +@beginTable +@hdr3col{property, type, description} +@row3col{label, @ref xrc_format_type_text, + Sheet page's title (required).} +@row3col{bitmap, @ref xrc_format_type_bitmap, + Bitmap shown alongside the label (default: none).} +@row3col{selected, @ref xrc_format_type_bool, + Is the page selected initially (only one page can be selected; default: 0)?} +@endTable + +Each @c propertysheetpage has exactly one non-toplevel window as its child. + @subsubsection xrc_wxradiobutton wxRadioButton -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{label, @ref xrc_format_type_text, + Label shown on the radio button (required).} +@row3col{value, @ref xrc_format_type_bool, + Initial value of the control (default: 0).} +@endTable + @subsubsection xrc_wxradiobox wxRadioBox -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{label, @ref xrc_format_type_text, + Label for the whole box (required).} +@row3col{dimension, integer, + Specifies the maximum number of rows (if style contains + @c wxRA_SPECIFY_ROWS) or columns (if style contains @c wxRA_SPECIFY_COLS) + for a two-dimensional radiobox (default: 1).} +@row3col{selection, integer, + Index of the initially selected item or -1 for no selection (default: -1).} +@row3col{content, , + Content of the control; this property has any number of @c \ XML + elements as its children, with the items text as their text values + (see below; default: empty).} +@endTable + +The @c \ elements have radio buttons' labels as their text values. They +can also have some optional XML @em attributes (not properties!): + +@beginTable +@hdr3col{attribute, type, description} +@row3col{tooltip, @ref xrc_format_type_string, + Tooltip to show over this ratio button (default: none).} +@row3col{helptext, @ref xrc_format_type_string, + Contextual help for this radio button (default: none).} +@row3col{enabled, @ref xrc_format_type_bool, + Is the button enabled (default: 1)?} +@row3col{hidden, @ref xrc_format_type_bool, + Is the button hidden initially (default: 0)?} +@endTable + +Example: +@code + + + + 1 + 0 + + Power 108 + Power 0 + WMMS 100.7 + Energy 98.3 + CHUM FM + 92FM + + + +@endcode + @subsubsection xrc_wxrichtextctrl wxRichTextCtrl -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{value, @ref xrc_format_type_text, + Initial value of the control (default: empty).} +@row3col{maxlength, integer, + Maximum length of the text entered (default: unlimited).} +@endTable + @subsubsection xrc_wxscrollbar wxScrollBar -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{value, integer, + Initial position of the scrollbar (default: 0).} +@row3col{range, integer, + Maximum value of the gauge (default: 10).} +@row3col{thumbsize, integer, + Size of the thumb (default: 1).} +@row3col{pagesize, integer, + Page size (default: 1).} +@endTable @subsubsection xrc_wxscrolledwindow wxScrolledWindow -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{scrollrate, @ref xrc_format_type_size, + Scroll rate in @em x and @em y directions (default: not set; + required if the window has a sizer child).} +@endTable + +wxScrolledWindow may have optional children: either exactly one +@ref xrc_format_sizers "sizer" child or any number of non-toplevel window +objects. If sizer child is used, wxSizer::FitInside() is used (instead of +wxSizer::Fit() as usual) and so the children don't determine scrolled window's +minimal size, they only affect @em virtual size. Usually, both @c scrollrate +and either @c size or @c minsize on containing sizer item should be used +in this case. + @subsubsection xrc_wxsimplehtmllistbox wxSimpleHtmlListBox -FIXME -@subsubsection xrc_wxslider wxSliderq -FIXME +wxSimpleHtmlListBox has same properties as @ref xrc_wxlistbox "wxListBox". +The only difference is that the text contained in @c \ elements is +HTML markup. Note that the markup has to be escaped: + +@code + + + <b>Bold</b> Milk + + +@endcode + +(X)HTML markup elements cannot be included directly: + +@code + + + + Bold Milk + + +@endcode + + +@subsubsection xrc_wxslider wxSlider + +@beginTable +@hdr3col{property, type, description} +@row3col{value, integer, + Initial value of the control (default: wxSL_DEFAULT_VALUE).} +@row3col{min, integer, + Minimum allowed value (default: wxSL_DEFAULT_MIN).} +@row3col{max, integer, + Maximum allowed value (default: wxSL_DEFAULT_MAX).} +@row3col{pagesize, integer, + Line size; number of steps the slider moves when the user moves + pages up or down (default: unset).} +@row3col{linesize, integer, + Line size; number of steps the slider moves when the user moves it + up or down a line (default: unset).} +@row3col{tickfreq, integer, + Tick marks frequency (Windows only; default: unset).} +@row3col{tick, integer, + Tick position (Windows only; default: unset).} +@row3col{thumb, integer, + Thumb length (Windows only; default: unset).} +@row3col{selmin, integer, + Selection start position (Windows only; default: unset).} +@row3col{selmax, integer, + Selection end position (Windows only; default: unset).} +@endTable + @subsubsection xrc_wxspinctrl wxSpinCtrl -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{value, integer, + Initial value of the control (default: wxSP_DEFAULT_VALUE).} +@row3col{min, integer, + Minimum allowed value (default: wxSP_DEFAULT_MIN).} +@row3col{max, integer, + Maximum allowed value (default: wxSP_DEFAULT_MAX).} +@endTable + @subsubsection xrc_wxsplitterwindow wxSplitterWindow -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{orientation, @ref xrc_format_type_string, + Orientation of the splitter, either "vertical" or "horizontal" (default: horizontal).} +@row3col{sashpos, integer, + Initial position of the sash (default: 0).} +@row3col{minsize, integer, + Minimum child size (default: not set).} +@row3col{minsize, @ref xrc_format_type_float, + Sash gravity, see wxSplitterWindow::SetSashGravity() (default: not set).} +@endTable + +wxSplitterWindow must have one or two children that are non-toplevel window +objects. If there's only one child, it is used as wxSplitterWindow's only +visible child. If there are two children, the first one is used for left/top +child and the second one for right/bottom child window. + @subsubsection xrc_wxsearchctrl wxSearchCtrl -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{value, @ref xrc_format_type_text, + Initial value of the control (default: empty).} +@endTable + @subsubsection xrc_wxstatusbar wxStatusBar -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{fields, integer, + Number of status bar fields (default: 1).} +@row3col{widths, @ref xrc_format_type_string, + Comma-separated list of @em fields integers. Each value specifies width + of one field; the values are interpreted using the same convention used + by wxStatusBar::SetStatusWidths().} +@row3col{styles, @ref xrc_format_type_string, + Comma-separated list of @em fields flags. Each value specifies status bar + fieldd style and can be one of @c wxSB_NORMAL, @c wxSB_FLAT or + @c wxSB_RAISED. See wxStatusBar::SetStatusStyles() for their description.} +@endTable + + @subsubsection xrc_wxstaticbitmap wxStaticBitmap -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{bitmap, @ref xrc_format_type_bitmap, + Bitmap to display (required).} +@endTable @subsubsection xrc_wxstaticbox wxStaticBox -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{label, @ref xrc_format_type_text, + Static box's label (required).} +@endTable + @subsubsection xrc_wxstaticline wxStaticLine -FIXME + +No additional properties. + @subsubsection xrc_wxstatictext wxStaticText -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{label, @ref xrc_format_type_text, + Label to display (required).} +@row3col{wrap, integer, + Number of characters per line to wrap the text for, see + wxStaticText::Wrap() (default: no wrap).} +@endTable @subsubsection xrc_wxtextctrl wxTextCtrl -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{value, @ref xrc_format_type_text, + Initial value of the control (default: empty).} +@row3col{maxlength, integer, + Maximum length of the text which can be entered by user (default: unlimited).} +@endTable + @subsubsection xrc_wxtogglebuttton wxToggleButton -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{label, @ref xrc_format_type_text, + Label to display on the button (required).} +@row3col{checked, @ref xrc_format_type_bool, + Should the button be checked/pressed initially (default: 0)?} +@endTable @subsubsection xrc_wxtoolbar wxToolBar -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{bitmapsize, @ref xrc_format_type_size, + Size of toolbar bitmaps (default: not set).} +@row3col{margins, @ref xrc_format_type_size, + Margins (default: platform default).} +@row3col{packing, integer, + Packing, see wxToolBar::SetToolPacking() (default: not set).} +@row3col{separation, integer, + Default separator size, see wxToolBar::SetToolSeparation() (default: not set).} +@row3col{dontattachtoframe, @ref xrc_format_type_bool, + If set to 0 and the toolbar object is child of a wxFrame, + wxFrame::SetToolBar() is called; otherwise, you have to add it to a frame + manually. The toolbar is attached by default, you have to set this property + to 1 to disable this behaviour (default: 0).} +@endTable + +A toolbar can have one or more child objects of any wxControl-derived class or +one of two pseudo-classes: @c separator or @c tool. + +The @c separator pseudo-class is used to insert separators into the toolbar and +has neither properties nor children. + +The @c tool pseudo-class objects specify toolbar buttons and have the following +properties: + +@beginTable +@hdr3col{property, type, description} +@row3col{bitmap, @ref xrc_format_type_bitmap, + Tool's bitmap (required).} +@row3col{bitmap2, @ref xrc_format_type_bitmap, + Bitmap for disabled tool (default: derived from @c bitmap).} +@row3col{label, @ref xrc_format_type_text, + Label to display on the tool (default: no label).} +@row3col{radio, @ref xrc_format_type_bool, + Item's kind is wxITEM_RADIO (default: 0)?} +@row3col{toggle, @ref xrc_format_type_bool, + Item's kind is wxITEM_CHECK (default: 0)?} +@row3col{tooltip, @ref xrc_format_type_text, + Tooltip to use for the tool (default: none).} +@row3col{longhelp, @ref xrc_format_type_text, + Help text shown in statusbar when the mouse is on the tool (default: none).} +@row3col{disabled, @ref xrc_format_type_bool, + Is the tool initially disabled (default: 0)?} +@endTable + +@c radio and @c toggle are mutually exclusive. + +Children that are neither @c tool nor @c separator must be instances of classes +derived from wxControl and are added to the toolbar using +wxToolBar::AddControl(). + +Example: +@code + + + + foo.png + + + + bar.png + + + + + + Just + a combobox + in the toolbar + + + + +@endcode + @subsubsection xrc_wxtreectrl wxTreeCtrl -FIXME + +No additional properties. + @subsubsection xrc_wxtreebook wxTreebook -FIXME + +No additional properties. + +A treebook can have one or more child objects of the @c treebookpage +pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its +@c notebookpage). @c treebookpage objects have the following properties: + +@beginTable +@hdr3col{property, type, description} +@row3col{depth, integer, + Page's depth in the labels tree (required; see below).} +@row3col{label, @ref xrc_format_type_text, + Sheet page's title (required).} +@row3col{bitmap, @ref xrc_format_type_bitmap, + Bitmap shown alongside the label (default: none).} +@row3col{selected, @ref xrc_format_type_bool, + Is the page selected initially (only one page can be selected; default: 0)?} +@endTable + +Each @c treebookpage has exactly one non-toplevel window as its child. + +The tree of labels is not described using nested @c treebookpage objects, but +using the @em depth property. Toplevel pages have depth 0, their child pages +have depth 1 and so on. A @c treebookpage's label is inserted as child of +the latest preceding page with depth equal to @em depth-1. For example, this +XRC markup: + +@code + + ... + + 0 + + ... + + + 1 + + ... + + + 2 + + ... + + + 1 + + ... + + + 2 + + ... + + + 0 + + ... + + +@endcode + +corresponds to the following tree of labels: + + - Page 1 + - Subpage 1A + - Subsubpage 1 + - Subpage 1B + - Subsubpage 2 + - Page 2 + @subsubsection xrc_wxwizard wxWizard -FIXME + +@beginTable +@hdr3col{property, type, description} +@row3col{bitmap, @ref xrc_format_type_bitmap, + Bitmap to display on the left side of the wizard (default: none).} +@endTable + +A wizard object can have one or more child objects of the wxWizardPage or +wxWizardPageSimple classes. They both support the following properties +(in addition to @ref xrc_format_std_props): + +@beginTable +@hdr3col{property, type, description} +@row3col{bitmap, @ref xrc_format_type_bitmap, + Page-specific bitmap (default: none).} +@endTable + +wxWizardPageSimple pages are automatically chained together; wxWizardPage pages +transitions must be handled programatically. @section xrc_format_sizers Sizers diff --git a/docs/tech/index.txt b/docs/tech/index.txt index 85582f627d..9b81fac4d8 100644 --- a/docs/tech/index.txt +++ b/docs/tech/index.txt @@ -14,7 +14,7 @@ tn0010.htm Compiling wxWidgets applications in the VC++ IDE tn0011.txt All about version numbers tn0012.txt wxWidgets platform, toolkit and library names tn0013.txt How to make a wxGTK distribution -tn0014.txt XRC resources format specification +tn0014.txt *** REMOVED *** (included in the manual now) tn0015.txt How to add new bitmaps to wxWidgets UI elements tn0016.txt How to add new files and libraries to wxWidgets build system (Bakefile) tn0017.txt How to write unit tests for wxWidgets classes diff --git a/docs/tech/tn0014.txt b/docs/tech/tn0014.txt deleted file mode 100644 index ce22912fdf..0000000000 --- a/docs/tech/tn0014.txt +++ /dev/null @@ -1,548 +0,0 @@ - XRC resources format specification - ================================== - - !!!!! NOT YET FINISHED !!!!! - -0. Introduction -=============== - -This note describes the file format used for storing XRC resources that are -used by wxXmlResource class. It is probably only useful for those implementing -dialog editors with XRC support. - -If you only want to use the resources, you can choose from a number of editors: - a) wxDesigner (http://www.roebling.de) - b) XRCed (wxPython/tools) - c) DialogBlocks (wxPython/tools) - -and others listed on the Resources section of the wxWidgets web -site. - -The XRC format is based on XML 1.0 (please consult W3C's specification). There -is no DTD available since it is not possible to fully describe the format with -the limited expressive power of DTDs. - - -Note: see also http://ldaptool.sourceforge.net/XRCGuide/XRCGuideSingle/ - - - -1. Terminology -============== - -The usual XML terminology applies. In particular, we shall use the terms -NODE, PROPERTY and VALUE in the XML sense: - - ... - -The term ATTRIBUTE is specific to XRC and refers to a subnode -of an or node that is itself not or . -In the example below, , - - -ATTRIBUTE VALUE is the content of all text elements within attribute tag. In the -above example, "wxSUNKEN_BORDER", "A label" and "10,10" are attribute values. -ATTRIBUTE TYPE defines what attribute values are valid for given attribute (you -can think of it as attribute value syntax definition). - - - -2. Elementary description -========================= - -XRC resource file is a well-formed XML 1.0 document. All elements of XRC file -are from the http://www.wxwidgets.org/wxxrc namespace. - -The root node of XRC document must be . The node has -optional "version" property. Default version (in absence of the version -property) is "0.0.0.0". The version consists of four integers separated by -periods. Version of XRC format changes only if there was an incompatible -change introduced (i.e. either the library cannot understand old resource -files or older versions of the library wouldn't understand the new format). -The first three integers are major, minor and release number of the wxWidgets -release when the change was introduced, the last one is revision number and -is 0 for the first incompatible change in given wxWidgets release, 1 for -the second etc. - -Differences between versions are described within this document in paragraphs -entitled "Version Note". - -The node contains namespace declaration, too: - - - -The node is only allowed to have and -subnodes, all of which must have the "name" property. - -The node represents a single object (GUI element) and it usually maps -directly to a wxWidgets class instance. It has the properties: "name", "class" -and "subclass". "class" must always be present, it tells XRC what wxWidgets -object should be created in this place. The other two are optional. "name" is -ID used to identify the object. It is the value passed to the XRCID() macro and -is also used to construct wxWindow's id and name attributes and must be unique -among all children of the nearest container object (wxDialog, wxFrame, -wxPanel, wxNotebook) upside from the object in XML nodes hierarchy (two distinct -containers may contain objects with same "name", though). "subclass" is -optional name of class whose constructor will be called instead of the -constructor for "class". Subclass must be available in the program that loads -the resource, must be derived from "class" and must be registered within -wxWidgets' RTTI system. - -Finally, an optional "insert_at" property may be present. Currently only the -values "begin" and "end" are supported, meaning to insert the object in the -beginning of the parent node objects list or to append it at the end (which is -the default if this property is absent). - -Example: - - - ... - - - node may have arbitrary child nodes. What child nodes and their -semantics are class-dependent and are defined later in this document. The user -is allowed to register new object handlers within XRC and extend it to accept -new classes (and therefore different 's child nodes). - - node is identical to , except that it does _not_ have -"class" property and has additional required property "ref". Its concept is -similar to Unix symlinks: value of the "ref" property is equal to the value of -"name" property of some existing node (called referred node) in the resources -(not necessary top-level). Referred node's "class" property and all subnodes -are copied in place of the referee node which is then processed as -regular node. If the node itself has child nodes, then -these nodes _override_ any nodes from the referred node. - -Example: - - - hello - 100,-1d - - - bar - - -is identical to: - - - hello - 100,-1d - - - bar - 100,-1d - - - - -3. Common attribute types -========================= - -There are several attribute types (see section 1. Terminology) that are common -to many attributes of different classes: - -String ------- -Any text. Some characters have special interpretation and are translated -by XRC parser according to this table: - "_" -> "&" ('&' is used to underline e.g. menu items in wxWidgets) - "__" -> "_" - "\n" -> line break (C character '\n') - "\r" -> carriage return (C character '\r') - "\t" -> tab (C character '\t') - "\\" -> "\" - (introduced in version 2.5.3.0, not done in earlier versions) - -Version Note: - '$' was used instead of '_' prior to version 2.3.0.1. - - -I18nString ----------- -Like String, but the value is translated to native language using wxLocale -at runtime (unless it was disabled by not passing wxXRC_USE_LOCALE flag to -wxXmlResource constructor). Used for strings that are "visible" in the GUI. - - -UnsignedInteger ---------------- -This is obvious. Only digits 0-9 may be present and there must be at least -one digit. - - -Integer -------- -Like UnsignedInteger but may be prefixed with '-' (ints less than zero). - - -Position --------- -Specifies (window's) position in 2D space. Syntax is ,[d] -where is valid value of Integer type. - - -Size ----- -Syntax is same as Position's syntax, but the values are interpreted as window -size (wxSize type) and not position (wxPosition type). - - -Style[wxSomeClass] ------------------- -List of style flags that can be passed to wxSomeClass' constructor. Flags are -written in same way as in C++ code (e.g. "wxSUNKEN_BORDER", -"wxHW_SCROLLBAR_NEVER") and are delimited with any combination of whitespaces -and '|'. Possible flags are class-dependent and are not described in this -technote. Please refer to wxWidgets manual for all styles that given class can -accept; if XRC does not accept a flag listed in wxWidgets documentation, it is -a bug. - - -Bitmap ------- -Attribute value is interpreted as filename (either absolute or relative to -the location of XRC resource file). In addition, attribute node may have -"stock_id" and "stock_client" properties. Their values may be any of wxArtID (or -wxArtClient respectively) values as used by wxArtProvider (because the user may -define own constants, effectively any string is legal here). Examples are -"wxART_FILE_OPEN" (id) or "wxART_MENU" (client). - -Any of "stock_id" or "stock_client" properties or the filename may be omitted. -XRC determines the bitmap to use according to this algorithm: - 1. If there is non-empty "stock_id" property, query wxArtProvider for the - bitmap (if there is no "stock_client", use default one, which is usually - wxART_OTHER; exceptions are noted in class-specific sections below). If - the query fails, continue to 2. - 2. Load the bitmap from the file in attribute value. - - -Boolean -------- -Boolean value, either "0" (false) or "1" (true). - - -Font ----- -Font value. A font can be described either in terms of its elementary -properties, or it can be derived from one of system fonts. The font node -may contain following subnodes (the table lists subnode name on the left and -variable type as per the definitions above on the right side): - -size UnsignedInteger -style normal | italic | slant -weight normal | bold | light -family roman | script | decorative | swiss | modern | teletype -underlined Boolean -face comma-separated list of faces -encoding charset of the font (meaningless in Unicode build), as string -sysfont symbolic name of system standard font - (one of wxSYS_*_FONT constants) -relativesize Float, font size relative to chosen system font's size; - can only be used when 'sysfont' is used and when 'size' is not - used - -All of them are optional, if they are missing, wxFont default is used. - -Examples: - - - arial,helvetica - 12 - - - - wxSYS_DEFAULT_GUI_FONT - bold - 1.5 - - - -Colour ------- -A colour value is either explicit RGB value in the standard #rrggbb format -where rr, gg and bb are hexadecimal case-insensitive values in the 00..FF -range, or a symbolic name. Symbolic names are wxSYS_COLOUR_* constants defined -by wxWidgets, written as strings. - -Example: - - wxSYS_COLOUR_SCROLLBAR - #FF0000 - - - -4. Supported classes -==================== - -Attributes are listed in tables in the following format: -attribute name attribute type default value, if any - [(optional remarks.................... - ...................................)] - -Common attributes ------------------ -These attributes are supported by all windows: - -exstyle Int -bg Colour -fg Colour -enabled Boolean true -focused Boolean false -hidden Boolean false -tooltip I18nString -font Font -help I18nString - -wxBitmap --------- -This is a special case, because it does not create a wxWindow instance but -creates wxBitmap instead. Another exceptional thing is that it does not have -any attributes. Instead, the node itself is interpreted as if it were attribute -of type Bitmap. - -Example: bitmaps/foo.gif - - -wxIcon ------- -Identical to wxBitmap class, except that it creates wxIcon instead of wxBitmap. - - -wxButton --------- -pos Position -1,-1 -size Size -1,-1 -style Style[wxButton] - -label I18nString -default Boolean false - (Is the button default button?) - - -wxCalendarCtrl --------------- -pos Position -1,-1 -size Size -1,-1 -style Style[wxCalendarCtrl] - - -wxCheckBox ----------- -pos Position -1,-1 -size Size -1,-1 -style Style[wxCheckBox] -checked Boolean false - - -wxCheckList ------------ -pos Position -1,-1 -size Size -1,-1 -style Style[wxCheckList] -content (see below) (empty) - -Optional "content" attribute does not have attribute value. Instead, -arbitrary number of nodes may be rooted under it (the control -is filled with strings contained in these nodes). Each -node must contain I18nString value and may have "checked" property -with possible values "0" or "1" indicating the the item is initially -checked. - -Example: - - - One - Two - Three - Four - - - - -wxDatePickerCtrl ----------------- -pos Position -1,-1 -size Size -1,-1 -style Style[wxDatePickerCtrl] - - -wxDialog --------- -pos Position -1,-1 -size Size -1,-1 -style Style[wxDialog] wxDEFAULT_DIALOG_STYLE -title I18nString "" -icon Bitmap (empty) -centered Boolean false - -wxDialog may have children objects. - - -wxFrame --------- -pos Position -1,-1 -size Size -1,-1 -style Style[wxDialog] wxDEFAULT_FRAME_STYLE -title I18nString "" -icon Bitmap (empty) -centered Boolean false - -wxFrame may have children objects. There can be at most one wxToolBar, -wxMenuBar and wxStatusBar children; objects of these types are automatically -set as frame's tool-, menu- and statusbar respectively. - - -wxMenu ------- - -wxMenu objects can contain objects of class "separator" and "break" as well as -normal menu items, of class "wxMenuItem" described below. The menu itself can -also have the following elements: - -label I18nString "" -help I18nString "" -enabled Boolean true -style Style[wxMenu] only wxMENU_TEAROFF currently - -wxMenuItem ----------- - -label I18nString "" -accel String "" -bitmap Bitmap (empty) -bitmap2 Bitmap checked bitmap, wxMSW only -checkable Boolean false -radio Boolean false -enabled Boolean true -checked Boolean false ("checkable" and "radio") - -wxMDIParentFrame ----------------- - -Supports same attributes and children nodes as wxFrame. Additionally, children -may be of the wxMDIChildFrame type. - - -wxMDIChildFrame ---------------- - -Supports same attributes and children nodes as wxFrame. - - -wxRadioBox ----------- - -This control may have "dimension" (major dimension) and (initial) "selection" -Integer subelements and a composite "content" element similar to wxCheckList -except that subelements can have additional attributes: - -tooltip I18nString "" -helptext I18nString "" -enabled Boolean 1 -hidden Boolean 0 - - -wxScrolledWindow ----------------- -pos Position -1,-1 -size Size -1,-1 -style Style[wxScrolledWindow] wxHSCROLL | wxVSCROLL -scrollrate Size 0,0 - -wxScolledWindow may have children objects. - - -wxSplitterWindow ----------------- -pos Position -1,-1 -size Size -1,-1 -style Style[wxSplitterWindow] wxSP_3D -sashpos Integer 0 - (Initial sash position) -minsize Integer -1 - (Minimal panel size) -orientation "horizontal"|"vertical" horizontal - -wxSplitterWindow must have at least one and at most two children objects. -If there's only one child object, it is passed to wxSplitterWindow::Initialize -and the splitter is created unsplit. If there are two children, the -splitter is created split, either horizontally or vertically depending -on the value of "orientation" attribute. - - -wxStaticText ------------- - -wxStaticText supports one class-specific attribute which wraps the controls -contents at the specified boundary: - -wrap Integer, in pixels None - -wxStatusBar ------------ -fields Integer number of fields -widths Width1, Width2, Width3, ... - - -wxToolBar ---------- -pos Position -1,-1 -size Size -1,-1 -style Style[wxToolBar] wxNO_BORDER|wxTB_HORIZONTAL -bitmapsize Size -1,-1 - (Size of contained bitmaps) -margins Size -1,-1 -packing Integer -1 -separation Integer -1 -bg Background colour None -dontattachtoframe Boolean False - -wxToolBar node may have children and nodes. Their class -may be either "tool", "separator" or any wxWidgets class derived from -wxControl. "tool" and "separator" are special pseudo-classes that may only -appear within wxToolBar node. Their attributes are as follows: - - separator - --------- - (doesn't have any attributes) - - tool - ---- - bitmap Bitmap - bitmap2 Bitmap wxNullBitmap - toggle Boolean 0 - radio Boolean 0 - disabled Boolean 0 - label I18nString "" - tooltip I18nString "" - longhelp I18nString "" - - Constraints: - At most one of "toggle" and "radio" attributes may be 1. - -Children objects are added to the toolbar using AddTool for "tool" class, -AddSeparator for "separator" and AddControl for other classes. - - - -5. More features -================ - -FIXME -- "platform" property handling - - -=== EOF === - -Version: $Id$ -- 2.45.2