From 1f1d2182ffe4feb82a1e674266f47d172ed3cb3c Mon Sep 17 00:00:00 2001 From: Francesco Montorsi Date: Fri, 28 Mar 2008 16:19:12 +0000 Subject: [PATCH] substitute '@b NB:' with '@note'; first partial revision of e*h headers; replace @beginEventTable with @beginEventTable{1} which provides the prototype of the event handler git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52900 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/doxygen/Doxyfile_inc | 2 +- docs/doxygen/wxwidgets.css | 142 +++++------ interface/bmpbuttn.h | 2 +- interface/bmpcbox.h | 2 +- interface/button.h | 2 +- interface/calctrl.h | 6 +- interface/checkbox.h | 2 +- interface/checklst.h | 2 +- interface/choice.h | 2 +- interface/cmdline.h | 2 +- interface/combo.h | 117 ++++++++- interface/combobox.h | 12 +- interface/datectrl.h | 5 +- interface/dc.h | 4 +- interface/dialog.h | 2 +- interface/dialup.h | 2 +- interface/dynarray.h | 2 +- interface/dynlib.h | 2 +- interface/editlbox.h | 30 ++- interface/encconv.h | 171 +++++++++---- interface/event.h | 481 +++++++++++++++++++++++-------------- interface/file.h | 2 +- interface/list.h | 6 +- interface/listbox.h | 2 +- interface/listctrl.h | 8 +- interface/log.h | 2 +- interface/menu.h | 2 +- interface/menuitem.h | 2 +- interface/notebook.h | 6 +- interface/odcombo.h | 2 +- interface/radiobox.h | 4 +- interface/radiobut.h | 4 +- interface/sashwin.h | 4 +- interface/spinbutt.h | 2 +- interface/spinctrl.h | 2 +- interface/string.h | 2 +- interface/textctrl.h | 2 +- interface/tglbtn.h | 4 +- interface/treectrl.h | 2 +- interface/txtstrm.h | 2 +- interface/window.h | 2 +- 41 files changed, 681 insertions(+), 373 deletions(-) diff --git a/docs/doxygen/Doxyfile_inc b/docs/doxygen/Doxyfile_inc index b487efb308..b0af2b1701 100644 --- a/docs/doxygen/Doxyfile_inc +++ b/docs/doxygen/Doxyfile_inc @@ -47,7 +47,7 @@ SUBGROUPING = YES # us to keep the headers readable and "implement" wxWidgets-specific commands. # event aliases -ALIASES = beginEventTable="\nEvents:" +ALIASES = beginEventTable{1}="\nEvents:

The following event handler macros redirect the events to member functions with a prototype: void handler(\1& event)

" ALIASES += event{1}="\li \1" ALIASES += event{2}="\li \1, \2" ALIASES += event{3}="\li \1, \2, \3" diff --git a/docs/doxygen/wxwidgets.css b/docs/doxygen/wxwidgets.css index 8ec3c853e7..fc85ed8d53 100644 --- a/docs/doxygen/wxwidgets.css +++ b/docs/doxygen/wxwidgets.css @@ -11,7 +11,7 @@ /* Doxygen classic styles ====================== -*/ +*/ BODY,H1,H2,H3,H4,H5,H6,P,CENTER,TD,TH,UL,DL,DIV { font-family: Geneva, Arial, Helvetica, sans-serif; @@ -30,8 +30,8 @@ H2 { H3 { font-size: 100%; } -CAPTION { - font-weight: bold +CAPTION { + font-weight: bold } DIV.qindex { width: 100%; @@ -88,42 +88,42 @@ A.qindexHL:hover { background-color: #6666cc; color: #ffffff; } -A.qindexHL:visited { - text-decoration: none; - background-color: #6666cc; - color: #ffffff +A.qindexHL:visited { + text-decoration: none; + background-color: #6666cc; + color: #ffffff } -A.el { - text-decoration: none; - font-weight: bold +A.el { + text-decoration: none; + font-weight: bold } -A.elRef { - font-weight: bold +A.elRef { + font-weight: bold } -A.code:link { - text-decoration: none; - font-weight: normal; +A.code:link { + text-decoration: none; + font-weight: normal; color: #0000FF } -A.code:visited { - text-decoration: none; - font-weight: normal; +A.code:visited { + text-decoration: none; + font-weight: normal; color: #0000FF } -A.codeRef:link { - font-weight: normal; +A.codeRef:link { + font-weight: normal; color: #0000FF } -A.codeRef:visited { - font-weight: normal; +A.codeRef:visited { + font-weight: normal; color: #0000FF } -A:hover { - text-decoration: none; - background-color: #f2f2ff +A:hover { + text-decoration: none; + background-color: #f2f2ff } -DL.el { - margin-left: -1cm +DL.el { + margin-left: -1cm } .fragment { font-family: monospace, fixed; @@ -141,12 +141,12 @@ PRE.fragment { padding-top: 4px; padding-bottom: 4px; } -DIV.ah { - background-color: black; - font-weight: bold; - color: #ffffff; - margin-bottom: 3px; - margin-top: 3px +DIV.ah { + background-color: black; + font-weight: bold; + color: #ffffff; + margin-bottom: 3px; + margin-top: 3px } DIV.groupHeader { @@ -155,10 +155,10 @@ DIV.groupHeader { margin-bottom: 6px; font-weight: bold; } -DIV.groupText { - margin-left: 16px; - font-style: italic; - font-size: 90% +DIV.groupText { + margin-left: 16px; + font-style: italic; + font-size: 90% } BODY { background: white; @@ -193,15 +193,15 @@ TD.indexvalue { border: 1px solid #CCCCCC; } TR.memlist { - background-color: #f0f0f0; + background-color: #f0f0f0; } -P.formulaDsp { - text-align: center; +P.formulaDsp { + text-align: center; } IMG.formulaDsp { } -IMG.formulaInl { - vertical-align: middle; +IMG.formulaInl { + vertical-align: middle; } SPAN.keyword { color: #008000 } SPAN.keywordtype { color: #604020 } @@ -328,7 +328,7 @@ SPAN.vhdllogic { color: #ff0000 } background-color: #FAFAFA; font-size: 90%; } -.search { +.search { color: #003399; font-weight: bold; } @@ -336,13 +336,13 @@ FORM.search { margin-bottom: 0px; margin-top: 0px; } -INPUT.search { +INPUT.search { font-size: 75%; color: #000080; font-weight: normal; background-color: #e8eef2; } -TD.tiny { +TD.tiny { font-size: 75%; } a { @@ -351,16 +351,16 @@ a { a:visited { color: #2A3798; } -.dirtab { +.dirtab { padding: 4px; border-collapse: collapse; border: 1px solid #84b0c7; } -TH.dirtab { +TH.dirtab { background: #e8eef2; font-weight: bold; } -HR { +HR { height: 1px; border: none; border-top: 1px solid black; @@ -372,8 +372,8 @@ HR { color: #606060; font-weight: normal; margin-left: 3px; -} -.memnav { +} +.memnav { background-color: #e8eef2; border: 1px solid #84b0c7; text-align: center; @@ -423,28 +423,28 @@ HR { font-family: sans-serif; margin:0.5em; } -.directory { - font-size: 9pt; - font-weight: bold; +.directory { + font-size: 9pt; + font-weight: bold; } -.directory h3 { - margin: 0px; - margin-top: 1em; - font-size: 11pt; +.directory h3 { + margin: 0px; + margin-top: 1em; + font-size: 11pt; } -.directory > h3 { - margin-top: 0; +.directory > h3 { + margin-top: 0; } -.directory p { - margin: 0px; - white-space: nowrap; +.directory p { + margin: 0px; + white-space: nowrap; } -.directory div { - display: none; - margin: 0px; +.directory div { + display: none; + margin: 0px; } -.directory img { - vertical-align: -30%; +.directory img { + vertical-align: -30%; } @@ -466,7 +466,7 @@ IMG.appearance { TABLE.appearance { width: 100%; text-align: center; - font-style: italic; + font-style: italic; font-size: 90%; /*font-weight: bold;*/ } @@ -491,6 +491,12 @@ SPAN.style, SPAN.event { color: #880000; } +SPAN.eventHandler { + padding: 5px; + background-color: #eeeeee; + font-family: monospace, fixed; +} + A[HREF="modules.html"] SPAN:before { content: "Categories / "; } diff --git a/interface/bmpbuttn.h b/interface/bmpbuttn.h index aca10ab692..66e175b6d3 100644 --- a/interface/bmpbuttn.h +++ b/interface/bmpbuttn.h @@ -55,7 +55,7 @@ Note that the wxBU_EXACTFIT style supported by wxButton is not used by this class as bitmap buttons don't have any minimal standard size by default. - @beginEventTable + @beginEventTable{wxCommandEvent} @event{EVT_BUTTON(id, func)}: Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked. @endEventTable diff --git a/interface/bmpcbox.h b/interface/bmpcbox.h index 8ea9b27b73..44f867b817 100644 --- a/interface/bmpcbox.h +++ b/interface/bmpcbox.h @@ -36,7 +36,7 @@ @todo create wxCB_PROCESS_ENTER rather than reusing wxTE_PROCESS_ENTER! - @beginEventTable + @beginEventTable{wxCommandEvent} @event{EVT_COMBOBOX(id, func)}: Process a wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on the list is selected. diff --git a/interface/button.h b/interface/button.h index ac8bb1d022..d912fca520 100644 --- a/interface/button.h +++ b/interface/button.h @@ -32,7 +32,7 @@ Creates a flat button. Windows and GTK+ only. @endStyleTable - @beginEventTable + @beginEventTable{wxCommandEvent} @event{EVT_BUTTON(id, func)}: Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked. @endEventTable diff --git a/interface/calctrl.h b/interface/calctrl.h index d894e1f821..ceb3e131ec 100644 --- a/interface/calctrl.h +++ b/interface/calctrl.h @@ -215,7 +215,7 @@ public: selection controls. (only generic) @endStyleTable - @beginEventTable + @beginEventTable{wxCalendarEvent} @event{EVT_CALENDAR(id, func)}: A day was double clicked in the calendar. @event{EVT_CALENDAR_SEL_CHANGED(id, func)}: @@ -232,8 +232,8 @@ public: @nativeimpl{wxgtk} - @see @ref overview_samplecalendar "Calendar sample", wxCalendarDateAttr, - wxCalendarEvent, wxDatePickerCtrl + @see @ref page_samples_calendar, wxCalendarDateAttr, wxCalendarEvent, + wxDatePickerCtrl */ class wxCalendarCtrl : public wxControl { diff --git a/interface/checkbox.h b/interface/checkbox.h index 2b99bc2467..8fe098e3b8 100644 --- a/interface/checkbox.h +++ b/interface/checkbox.h @@ -29,7 +29,7 @@ Makes the text appear on the left of the checkbox. @endStyleTable - @beginEventTable + @beginEventTable{wxCommandEvent} @event{EVT_CHECKBOX(id, func)}: Process a wxEVT_COMMAND_CHECKBOX_CLICKED event, when the checkbox is clicked. diff --git a/interface/checklst.h b/interface/checklst.h index 2e13c53661..80c5763f37 100644 --- a/interface/checklst.h +++ b/interface/checklst.h @@ -20,7 +20,7 @@ Please note that wxCheckListBox uses client data in its implementation, and therefore this is not available to the application. - @beginEventTable + @beginEventTable{wxCommandEvent} @event{EVT_CHECKLISTBOX(id, func)}: Process a wxEVT_COMMAND_CHECKLISTBOX_TOGGLED event, when an item in the check list box is checked or unchecked. diff --git a/interface/choice.h b/interface/choice.h index c138bbed01..48ff01128a 100644 --- a/interface/choice.h +++ b/interface/choice.h @@ -19,7 +19,7 @@ Sorts the entries alphabetically. @endStyleTable - @beginEventTable + @beginEventTable{wxCommandEvent} @event{EVT_CHOICE(id, func)}: Process a wxEVT_COMMAND_CHOICE_SELECTED event, when an item on the list is selected. diff --git a/interface/cmdline.h b/interface/cmdline.h index 56cd319a2b..110364bb6f 100644 --- a/interface/cmdline.h +++ b/interface/cmdline.h @@ -70,7 +70,7 @@ public: /** Frees resources allocated by the object. - @b NB: destructor is not virtual, don't use this class polymorphically. + @note destructor is not virtual, don't use this class polymorphically. */ ~wxCmdLineParser(); diff --git a/interface/combo.h b/interface/combo.h index 3fabbbc91a..744efd2b5e 100644 --- a/interface/combo.h +++ b/interface/combo.h @@ -10,9 +10,10 @@ @class wxComboPopup @wxheader{combo.h} - In order to use a custom popup with wxComboCtrl, - an interface class must be derived from wxComboPopup. For more information - how to use it, see @ref overview_wxcomboctrl "Setting Custom Popup for + In order to use a custom popup with wxComboCtrl, an interface class must + be derived from wxComboPopup. + + For more information on how to use it, see @ref overview_wxcomboctrl "Setting Custom Popup for wxComboCtrl". @library{wxcore} @@ -148,10 +149,108 @@ public: @class wxComboCtrl @wxheader{combo.h} - A combo control is a generic combobox that allows totally - custom popup. In addition it has other customization features. - For instance, position and size of the dropdown button - can be changed. + A combo control is a generic combobox that allows totally custom popup. + In addition it has other customization features. + For instance, position and size of the dropdown button can be changed. + + @section wxcomboctrl_custompopup Setting Custom Popup for wxComboCtrl + + wxComboCtrl needs to be told somehow which control to use and this is done + by SetPopupControl(). + However, we need something more than just a wxControl in this method as, + for example, we need to call SetStringValue("initial text value") and + wxControl doesn't have such method. So we also need a wxComboPopup which + is an interface which must be implemented by a control to be usable as a popup. + + We couldn't derive wxComboPopup from wxControl as this would make it + impossible to have a class deriving from a wxWidgets control and from it, + so instead it is just a mix-in. + + Here's a minimal sample of wxListView popup: + + @code + #include + #include + + class wxListViewComboPopup : public wxListView, + public wxComboPopup + { + public: + + // Initialize member variables + virtual void Init() + { + m_value = -1; + } + + // Create popup control + virtual bool Create(wxWindow* parent) + { + return wxListView::Create(parent,1,wxPoint(0,0),wxDefaultSize); + } + + // Return pointer to the created control + virtual wxWindow *GetControl() { return this; } + + // Translate string into a list selection + virtual void SetStringValue(const wxString& s) + { + int n = wxListView::FindItem(-1,s); + if ( n >= 0 && n < wxListView::GetItemCount() ) + wxListView::Select(n); + } + + // Get list selection as a string + virtual wxString GetStringValue() const + { + if ( m_value >= 0 ) + return wxListView::GetItemText(m_value); + return wxEmptyString; + } + + // Do mouse hot-tracking (which is typical in list popups) + void OnMouseMove(wxMouseEvent& event) + { + // TODO: Move selection to cursor + } + + // On mouse left up, set the value and close the popup + void OnMouseClick(wxMouseEvent& WXUNUSED(event)) + { + m_value = wxListView::GetFirstSelected(); + + // TODO: Send event as well + + Dismiss(); + } + + protected: + int m_value; // current item index + + private: + DECLARE_EVENT_TABLE() + }; + + BEGIN_EVENT_TABLE(wxListViewComboPopup, wxListView) + EVT_MOTION(wxListViewComboPopup::OnMouseMove) + EVT_LEFT_UP(wxListViewComboPopup::OnMouseClick) + END_EVENT_TABLE() + @endcode + + Here's how you would create and populate it in a dialog constructor: + + @code + wxComboCtrl* comboCtrl = new wxComboCtrl(this,wxID_ANY,wxEmptyString); + + wxListViewComboPopup* popupCtrl = new wxListViewComboPopup(); + + comboCtrl->SetPopupControl(popupCtrl); + + // Populate using wxListView methods + popupCtrl->InsertItem(popupCtrl->GetItemCount(),wxT("First Item")); + popupCtrl->InsertItem(popupCtrl->GetItemCount(),wxT("Second Item")); + popupCtrl->InsertItem(popupCtrl->GetItemCount(),wxT("Third Item")); + @endcode @beginStyleTable @style{wxCB_READONLY}: @@ -172,7 +271,7 @@ public: Drop button will behave more like a standard push button. @endStyleTable - @beginEventTable + @beginEventTable{wxCommandEvent} @event{EVT_TEXT(id, func)}: Process a wxEVT_COMMAND_TEXT_UPDATED event, when the text changes. @event{EVT_TEXT_ENTER(id, func)}: @@ -588,7 +687,7 @@ public: /** Sets the text for the combo control text field. - @b NB: For a combo control with @c wxCB_READONLY style the + @note For a combo control with @c wxCB_READONLY style the string must be accepted by the popup (for instance, exist in the dropdown list), otherwise the call to SetValue() is ignored */ diff --git a/interface/combobox.h b/interface/combobox.h index 082f052cff..ac98f43f63 100644 --- a/interface/combobox.h +++ b/interface/combobox.h @@ -18,9 +18,8 @@ A combobox permits a single selection only. Combobox items are numbered from zero. - If you need a customized combobox, have a look at wxComboCtrl, - wxOwnerDrawnComboBox, wxComboPopup - and the ready-to-use wxBitmapComboBox. + If you need a customized combobox, have a look at wxComboCtrl, wxOwnerDrawnComboBox, + wxComboPopup and the ready-to-use wxBitmapComboBox. @beginStyleTable @style{wxCB_SIMPLE}: @@ -40,7 +39,7 @@ only. @endStyleTable - @beginEventTable + @beginEventTable{wxCommandEvent} @event{EVT_COMBOBOX(id, func)}: Process a wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on the list is selected. Note that calling GetValue returns the new @@ -275,8 +274,9 @@ public: /** Sets the text for the combobox text field. - @b NB: For a combobox with @c wxCB_READONLY style the string must be in - the combobox choices list, otherwise the call to SetValue() is ignored. + + @note For a combobox with @c wxCB_READONLY style the string must be in + the combobox choices list, otherwise the call to SetValue() is ignored. @param text The text to set. diff --git a/interface/datectrl.h b/interface/datectrl.h index c84b3c75d3..501b03cc9d 100644 --- a/interface/datectrl.h +++ b/interface/datectrl.h @@ -42,10 +42,9 @@ default date representation in the system. @endStyleTable - @beginEventTable + @beginEventTable{wxDateEvent} @event{EVT_DATE_CHANGED(id, func)}: - This event fires when the user changes the current selection in the - control. + This event fires when the user changes the current selection in the control. @endEventTable @library{wxadv} diff --git a/interface/dc.h b/interface/dc.h index 80a6d7d02d..3b6ba062d8 100644 --- a/interface/dc.h +++ b/interface/dc.h @@ -354,7 +354,7 @@ public: /** Draws the text rotated by @a angle degrees. - @b NB: Under Win9x only TrueType fonts can be drawn by this function. In + @note Under Win9x only TrueType fonts can be drawn by this function. In particular, a font different from @c wxNORMAL_FONT should be used as the latter is not a TrueType font. @c wxSWISS_FONT is an example of a font which is. @@ -400,7 +400,7 @@ public: the string. See GetTextExtent() for how to get the dimensions of a text string, which can be used to position the text more precisely. - @b NB: under wxGTK the current + @note under wxGTK the current @ref getlogicalfunction() "logical function" is used by this function but it is ignored by wxMSW. Thus, you should avoid using logical functions with this function in portable programs. diff --git a/interface/dialog.h b/interface/dialog.h index 723ed67ccc..73543c1f58 100644 --- a/interface/dialog.h +++ b/interface/dialog.h @@ -438,7 +438,7 @@ public: static wxDialogLayoutAdapter* SetLayoutAdapter(wxDialogLayoutAdapter* adapter); /** - @b NB: This function is deprecated and doesn't work for all ports, just use + @note This function is deprecated and doesn't work for all ports, just use ShowModal() to show a modal dialog instead. Allows the programmer to specify whether the dialog box is modal (Show() blocks control diff --git a/interface/dialup.h b/interface/dialup.h index 0b83e33765..2b72e9786b 100644 --- a/interface/dialup.h +++ b/interface/dialup.h @@ -108,7 +108,7 @@ public: /** Returns @true if the computer has a permanent network connection (i.e. is on a LAN) and so there is no need to use Dial() function to go online. - @b NB: this functions tries to guess the result and it is not always + @note this functions tries to guess the result and it is not always guaranteed to be correct, so it is better to ask user for confirmation or give him a possibility to override it. */ diff --git a/interface/dynarray.h b/interface/dynarray.h index fbb76b2f06..d5bc122cb9 100644 --- a/interface/dynarray.h +++ b/interface/dynarray.h @@ -282,7 +282,7 @@ public: Linear search is used for the wxArray and wxObjArray classes but binary search in the sorted array is used for wxSortedArray (this is why searchFromEnd parameter doesn't make sense for it). - @b NB: even for wxObjArray classes, the operator==() of the elements in the + @note even for wxObjArray classes, the operator==() of the elements in the array is @b not used by this function. It searches exactly the given element in the array and so will only succeed if this element had been previously added to the array, but fail even if another, identical, element is diff --git a/interface/dynlib.h b/interface/dynlib.h index c5abb1b599..c38088c1c6 100644 --- a/interface/dynlib.h +++ b/interface/dynlib.h @@ -140,7 +140,7 @@ public: This function returns a valid handle for the main program itself. Notice that the @NULL return value is valid for some systems (i.e. doesn't mean that the function failed). - @b NB: This function is Unix specific. It will always fail under Windows + @note This function is Unix specific. It will always fail under Windows or OS/2. */ wxDllType GetProgramHandle(); diff --git a/interface/editlbox.h b/interface/editlbox.h index 9e74f4c36d..dfc74a4cd3 100644 --- a/interface/editlbox.h +++ b/interface/editlbox.h @@ -10,8 +10,8 @@ @class wxEditableListBox @wxheader{editlbox.h} - An editable listbox is composite control that lets the - user easily enter, delete and reorder a list of strings. + An editable listbox is composite control that lets the user easily enter, + delete and reorder a list of strings. @beginStyleTable @style{wxEL_ALLOW_NEW}: @@ -23,18 +23,22 @@ @style{wxEL_NO_REORDER}: Does not allow the user to reorder the strings. @style{wxEL_DEFAULT_STYLE}: - wxEL_ALLOW_NEW|wxEL_ALLOW_EDIT|wxEL_ALLOW_DELETE + Default style: wxEL_ALLOW_NEW|wxEL_ALLOW_EDIT|wxEL_ALLOW_DELETE. @endStyleTable @library{wxadv} - @category{FIXME} + @category{ctrl} @see wxListBox */ class wxEditableListBox : public wxPanel { public: - //@{ + /** + Default ctor. + */ + wxEditableListBox(); + /** Constructor, creating and showing a list box. @@ -47,8 +51,7 @@ public: @param pos Window position. @param size - Window size. If wxDefaultSize is specified then the window is - sized + Window size. If wxDefaultSize is specified then the window is sized appropriately. @param style Window style. See wxEditableListBox. @@ -57,14 +60,12 @@ public: @see Create() */ - wxEditableListBox(); wxEditableListBox(wxWindow* parent, wxWindowID id, const wxString& label, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxEL_DEFAULT_STYLE, const wxString& name = "editableListBox"); - //@} /** Destructor, destroying the list box. @@ -72,8 +73,8 @@ public: ~wxEditableListBox(); /** - Creates the editable listbox for two-step construction. See wxEditableListBox() - for further details. + Creates the editable listbox for two-step construction. + See wxEditableListBox() for further details. */ bool Create(wxWindow* parent, wxWindowID id, const wxString& label, @@ -86,5 +87,12 @@ public: Replaces current contents with given strings. */ void SetStrings(const wxArrayString& strings); + + + /** + Returns in the given array the current contents of the control + (the array will be erased before control's contents are appended). + */ + void GetSelections(wxArrayString& strings) const; }; diff --git a/interface/encconv.h b/interface/encconv.h index 4e4c5940de..a7821321ce 100644 --- a/interface/encconv.h +++ b/interface/encconv.h @@ -10,18 +10,25 @@ @class wxEncodingConverter @wxheader{encconv.h} - This class is capable of converting strings between two - 8-bit encodings/charsets. It can also convert from/to Unicode (but only - if you compiled wxWidgets with wxUSE_WCHAR_T set to 1). Only a limited subset - of encodings is supported by wxEncodingConverter: + This class is capable of converting strings between two 8-bit encodings/charsets. + It can also convert from/to Unicode (but only if you compiled wxWidgets + with wxUSE_WCHAR_T set to 1). + + Only a limited subset of encodings is supported by wxEncodingConverter: @c wxFONTENCODING_ISO8859_1..15, @c wxFONTENCODING_CP1250..1257 and @c wxFONTENCODING_KOI8. + @note + + Please use wxMBConv classes instead if possible. wxCSConv has much better + support for various encodings than wxEncodingConverter. + wxEncodingConverter is useful only if you rely on wxCONVERT_SUBSTITUTE mode + of operation (see wxEncodingConverter::Init()). + @library{wxbase} @category{misc} - @see wxFontMapper, wxMBConv, @ref overview_nonenglishoverview "Writing - non-English applications" + @see wxFontMapper, wxMBConv, @ref overview_nonenglish */ class wxEncodingConverter : public wxObject { @@ -33,88 +40,146 @@ public: /** Return @true if (any text in) multibyte encoding @a encIn can be converted to - another one (@e encOut) losslessly. - Do not call this method with @c wxFONTENCODING_UNICODE as either - parameter, it doesn't make sense (always works in one sense and always depends + another one (@a encOut) losslessly. + + Do not call this method with @c wxFONTENCODING_UNICODE as either parameter, + it doesn't make sense (always works in one sense and always depends on the text to convert in the other). */ static bool CanConvert(wxFontEncoding encIn, wxFontEncoding encOut); - //@{ /** - Convert wxString and return new wxString object. + @name Conversion functions + + @{ + */ + /** + Convert input string according to settings passed to Init() and writes + the result to output. + + All the Convert() function overloads return @true if the conversion was + lossless and @false if at least one of the characters couldn't be converted + was and replaced with '?' in the output. + + Note that if @c wxCONVERT_SUBSTITUTE was passed to Init(), substitution is + considered a lossless operation. + + @note You must call Init() before using this method! + + @note wchar_t versions of the method are not available if wxWidgets was + compiled with @c wxUSE_WCHAR_T set to 0. */ bool Convert(const char* input, char* output) const; - const bool Convert(const wchar_t* input, wchar_t* output) const; - const bool Convert(const char* input, wchar_t* output) const; - const bool Convert(const wchar_t* input, char* output) const; - const bool Convert(char* str) const; - const bool Convert(wchar_t* str) const; - const wxString Convert(const wxString& input) const; + bool Convert(const wchar_t* input, wchar_t* output) const; + bool Convert(const char* input, wchar_t* output) const; + bool Convert(const wchar_t* input, char* output) const; + + /** + Convert input string according to settings passed to Init() in-place, + i.e. write the result to the same memory area. + + See the Convert(const char*,char*) const overload for more info. + */ + bool Convert(char* str) const; + bool Convert(wchar_t* str) const; + + /** + Convert a wxString and return a new wxString object. + + See the Convert(const char*,char*) const overload for more info. + */ + wxString Convert(const wxString& input) const; //@} + /** - Similar to - GetPlatformEquivalents(), - but this one will return ALL + Similar to GetPlatformEquivalents(), but this one will return ALL equivalent encodings, regardless of the platform, and including itself. - This platform's encodings are before others in the array. And again, if @a enc - is in the array, - it is the very first item in it. + + This platform's encodings are before others in the array. + And again, if @a enc is in the array, it is the very first item in it. */ static wxFontEncodingArray GetAllEquivalents(wxFontEncoding enc); /** - Return equivalents for given font that are used - under given platform. Supported platforms: - wxPLATFORM_UNIX - wxPLATFORM_WINDOWS - wxPLATFORM_OS2 - wxPLATFORM_MAC - wxPLATFORM_CURRENT + Return equivalents for given font that are used under given platform. + + Supported platforms: + @li wxPLATFORM_UNIX + @li wxPLATFORM_WINDOWS + @li wxPLATFORM_OS2 + @li wxPLATFORM_MAC + @li wxPLATFORM_CURRENT + wxPLATFORM_CURRENT means the platform this binary was compiled for. + Examples: - Equivalence is defined in terms of convertibility: - two encodings are equivalent if you can convert text between - then without losing information (it may - and will - happen - that you lose special chars like quotation marks or em-dashes - but you shouldn't lose any diacritics and language-specific - characters when converting between equivalent encodings). + @verbatim + current platform enc returned value + ---------------------------------------------- + unix CP1250 {ISO8859_2} + unix ISO8859_2 {ISO8859_2} + windows ISO8859_2 {CP1250} + unix CP1252 {ISO8859_1,ISO8859_15} + @endverbatim + + Equivalence is defined in terms of convertibility: two encodings are + equivalent if you can convert text between then without losing + information (it may - and will - happen that you lose special chars + like quotation marks or em-dashes but you shouldn't lose any diacritics + and language-specific characters when converting between equivalent encodings). + Remember that this function does @b NOT check for presence of fonts in system. It only tells you what are most suitable encodings. (It usually returns only one encoding.) + + @note Note that argument enc itself may be present in the returned array, + so that you can, as a side-effect, detect whether the encoding is + native for this platform or not. + + @note Convert() is not limited to converting between equivalent encodings, + it can convert between two arbitrary encodings. + + @note If @a enc is present in the returned array, then it is always the first + item of it. + + @note Please note that the returned array may contain no items at all. */ static wxFontEncodingArray GetPlatformEquivalents(wxFontEncoding enc, - int platform = wxPLATFORM_CURRENT); + int platform = wxPLATFORM_CURRENT); /** - Initialize conversion. Both output or input encoding may - be wxFONTENCODING_UNICODE, but only if wxUSE_ENCODING is set to 1. - All subsequent calls to Convert() - will interpret its argument + Initialize the conversion. + + Both output or input encoding may be wxFONTENCODING_UNICODE, but only + if wxUSE_ENCODING is set to 1. + + All subsequent calls to Convert() will interpret its argument as a string in @a input_enc encoding and will output string in @a output_enc encoding. + You must call this method before calling Convert. You may call it more than once in order to switch to another conversion. - @e Method affects behaviour of Convert() in case input character - cannot be converted because it does not exist in output encoding: - @b wxCONVERT_STRICT - - follow behaviour of GNU Recode - - just copy unconvertible characters to output and don't change them - (its integer value will stay the same) - - @b wxCONVERT_SUBSTITUTE + @a method affects behaviour of Convert() in case input character + cannot be converted because it does not exist in output encoding: - try some (lossy) substitutions - - e.g. replace unconvertible latin capitals with acute by ordinary - capitals, replace en-dash or em-dash by '-' etc. + @li @b wxCONVERT_STRICT: follow behaviour of GNU Recode - just copy + unconvertible characters to output and don't change them + (its integer value will stay the same) + @li @b wxCONVERT_SUBSTITUTE: try some (lossy) substitutions - e.g. + replace unconvertible latin capitals with acute by ordinary + capitals, replace en-dash or em-dash by '-' etc. Both modes guarantee that output string will have same length as input string. + + @return @false if given conversion is impossible, @true otherwise + (conversion may be impossible either if you try to convert + to Unicode with non-Unicode build of wxWidgets or if input + or output encoding is not supported). */ bool Init(wxFontEncoding input_enc, wxFontEncoding output_enc, int method = wxCONVERT_STRICT); diff --git a/interface/event.h b/interface/event.h index 4ea10eb245..e97a4d699a 100644 --- a/interface/event.h +++ b/interface/event.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: event.h -// Purpose: interface of wxKeyEvent +// Purpose: interface of wx*Event classes // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -23,9 +23,10 @@ Both key events provide untranslated key codes while the char event carries the translated one. The untranslated code for alphanumeric keys is always an upper case value. For the other keys it is one of @c WXK_XXX values - from the @ref overview_keycodes "keycodes table". The translated key is, in - general, the character the user expects to appear as the result of the key - combination when typing the text into a text entry zone, for example. + from the @ref page_keycodes. + The translated key is, in general, the character the user expects to appear + as the result of the key combination when typing the text into a text entry + zone, for example. A few examples to clarify this (all assume that CAPS LOCK is unpressed and the standard US keyboard): when the @c 'A' key is pressed, the key down @@ -37,33 +38,43 @@ Although in this simple case it is clear that the correct key code could be found in the key down event handler by checking the value returned by - wxKeyEvent::ShiftDown, in general you should use - @c EVT_CHAR for this as for non-alphanumeric keys the translation is - keyboard-layout dependent and can only be done properly by the system itself. + wxKeyEvent::ShiftDown(), in general you should use @c EVT_CHAR for this as + for non-alphanumeric keys the translation is keyboard-layout dependent and + can only be done properly by the system itself. Another kind of translation is done when the control key is pressed: for example, for CTRL-A key press the key down event still carries the - same key code @c 'a' as usual but the char event will have key code of - 1, the ASCII value of this key combination. + same key code @c 'a' as usual but the char event will have key code of 1, + the ASCII value of this key combination. You may discover how the other keys on your system behave interactively by - running the text() wxWidgets sample and pressing some keys + running the @ref page_samples_text wxWidgets sample and pressing some keys in any of the text controls shown in it. - @b Note: If a key down (@c EVT_KEY_DOWN) event is caught and - the event handler does not call @c event.Skip() then the corresponding - char event (@c EVT_CHAR) will not happen. This is by design and - enables the programs that handle both types of events to be a bit - simpler. - - @b Note for Windows programmers: The key and char events in wxWidgets are - similar to but slightly different from Windows @c WM_KEYDOWN and - @c WM_CHAR events. In particular, Alt-x combination will generate a char - event in wxWidgets (unless it is used as an accelerator). - @b Tip: be sure to call @c event.Skip() for events that you don't process in key event function, otherwise menu shortcuts may cease to work under Windows. + @note If a key down (@c EVT_KEY_DOWN) event is caught and the event handler + does not call @c event.Skip() then the corresponding char event + (@c EVT_CHAR) will not happen. + This is by design and enables the programs that handle both types of + events to be a bit simpler. + + @note For Windows programmers: The key and char events in wxWidgets are + similar to but slightly different from Windows @c WM_KEYDOWN and + @c WM_CHAR events. In particular, Alt-x combination will generate a + char event in wxWidgets (unless it is used as an accelerator). + + + @beginEventTable{wxKeyEvent} + @event{EVT_KEY_DOWN(func)}: + Process a wxEVT_KEY_DOWN event (any key has been pressed). + @event{EVT_KEY_UP(func)}: + Process a wxEVT_KEY_UP event (any key has been released). + @event{EVT_CHAR(func)}: + Process a wxEVT_CHAR event. + @endEventTable + @library{wxcore} @category{events} */ @@ -71,61 +82,70 @@ class wxKeyEvent : public wxEvent { public: /** - Constructor. Currently, the only valid event types are wxEVT_CHAR and - wxEVT_CHAR_HOOK. + Constructor. + Currently, the only valid event types are @c wxEVT_CHAR and @c wxEVT_CHAR_HOOK. */ - wxKeyEvent(wxEventType keyEventType); + wxKeyEvent(wxEventType keyEventType = wxEVT_NULL); /** Returns @true if the Alt key was down at the time of the key event. - Notice that GetModifiers() is easier to use - correctly than this function so you should consider using it in new code. + + Notice that GetModifiers() is easier to use correctly than this function + so you should consider using it in new code. */ bool AltDown() const; /** CMD is a pseudo key which is the same as Control for PC and Unix - platforms but the special APPLE (a.k.a as COMMAND) key under - Macs: it makes often sense to use it instead of, say, ControlDown() because Cmd + platforms but the special APPLE (a.k.a as COMMAND) key under Macs: + it makes often sense to use it instead of, say, ControlDown() because Cmd key is used for the same thing under Mac as Ctrl elsewhere (but Ctrl still exists, just not used for this purpose under Mac). So for non-Mac platforms - this is the same as ControlDown() and under - Mac this is the same as MetaDown(). + this is the same as ControlDown() and under Mac this is the same as MetaDown(). */ bool CmdDown() const; /** Returns @true if the control key was down at the time of the key event. - Notice that GetModifiers() is easier to use - correctly than this function so you should consider using it in new code. + + Notice that GetModifiers() is easier to use correctly than this function + so you should consider using it in new code. */ bool ControlDown() const; /** Returns the virtual key code. ASCII events return normal ASCII values, - while non-ASCII events return values such as @b WXK_LEFT for the - left cursor key. See Keycodes() for a full list of - the virtual key codes. + while non-ASCII events return values such as @b WXK_LEFT for the left cursor + key. See @ref page_keycodes for a full list of the virtual key codes. + Note that in Unicode build, the returned value is meaningful only if the user entered a character that can be represented in current locale's default - charset. You can obtain the corresponding Unicode character using - GetUnicodeKey(). + charset. You can obtain the corresponding Unicode character using GetUnicodeKey(). */ int GetKeyCode() const; /** Return the bitmask of modifier keys which were pressed when this event - happened. See @ref overview_keymodifiers "key modifier constants" for the full - list - of modifiers. + happened. See @ref page_keymodifiers for the full list of modifiers. + Notice that this function is easier to use correctly than, for example, - ControlDown() because when using the latter you - also have to remember to test that none of the other modifiers is pressed: + ControlDown() because when using the latter you also have to remember to + test that none of the other modifiers is pressed: - and forgetting to do it can result in serious program bugs (e.g. program not - working with European keyboard layout where ALTGR key which is seen by - the program as combination of CTRL and ALT is used). On the - other hand, you can simply write + @code + if ( ControlDown() && !AltDown() && !ShiftDown() && !MetaDown() ) + ... handle Ctrl-XXX ... + @endcode + + and forgetting to do it can result in serious program bugs (e.g. program + not working with European keyboard layout where ALTGR key which is seen by + the program as combination of CTRL and ALT is used). On the other hand, + you can simply write: + + @code + if ( GetModifiers() == wxMOD_CONTROL ) + ... handle Ctrl-XXX ... + @endcode with this function. */ @@ -136,27 +156,30 @@ public: Obtains the position (in client coordinates) at which the key was pressed. */ wxPoint GetPosition() const; - const void GetPosition(long* x, long* y) const; + void GetPosition(long* x, long* y) const; //@} /** Returns the raw key code for this event. This is a platform-dependent scan code which should only be used in advanced applications. - @b NB: Currently the raw key codes are not supported by all ports, use - @c #ifdef wxHAS_RAW_KEY_CODES to determine if this feature is available. + + @note Currently the raw key codes are not supported by all ports, use + @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available. */ wxUint32 GetRawKeyCode() const; /** Returns the low level key flags for this event. The flags are platform-dependent and should only be used in advanced applications. - @b NB: Currently the raw key flags are not supported by all ports, use - @c #ifdef wxHAS_RAW_KEY_CODES to determine if this feature is available. + + @note Currently the raw key flags are not supported by all ports, use + @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available. */ wxUint32 GetRawKeyFlags() const; /** Returns the Unicode character corresponding to this key event. + This function is only available in Unicode build, i.e. when @c wxUSE_UNICODE is 1. */ @@ -168,86 +191,36 @@ public: wxCoord GetX() const; /** - Returns the Y (in client coordinates) position of the event. + Returns the Y position (in client coordinates) of the event. */ wxCoord GetY() const; /** - Returns @true if either CTRL or ALT keys was down - at the time of the key event. Note that this function does not take into - account neither SHIFT nor META key states (the reason for ignoring - the latter is that it is common for NUMLOCK key to be configured as - META under X but the key presses even while NUMLOCK is on should - be still processed normally). + Returns @true if either CTRL or ALT keys was down at the time of the + key event. + + Note that this function does not take into account neither SHIFT nor + META key states (the reason for ignoring the latter is that it is + common for NUMLOCK key to be configured as META under X but the key + presses even while NUMLOCK is on should be still processed normally). */ bool HasModifiers() const; /** Returns @true if the Meta key was down at the time of the key event. - Notice that GetModifiers() is easier to use - correctly than this function so you should consider using it in new code. + + Notice that GetModifiers() is easier to use correctly than this function + so you should consider using it in new code. */ bool MetaDown() const; /** Returns @true if the shift key was down at the time of the key event. - Notice that GetModifiers() is easier to use - correctly than this function so you should consider using it in new code. - */ - bool ShiftDown() const; - - /** - bool m_altDown - @b Deprecated: Please use GetModifiers() - instead! - @true if the Alt key is pressed down. - */ - - /** - bool m_controlDown - @b Deprecated: Please use GetModifiers() - instead! - @true if control is pressed down. - */ - - - /** - long m_keyCode - @b Deprecated: Please use GetKeyCode() - instead! - Virtual keycode. See Keycodes() for a list of identifiers. - */ - - - /** - bool m_metaDown - @b Deprecated: Please use GetModifiers() - instead! - @true if the Meta key is pressed down. - */ - - - /** - bool m_shiftDown - @b Deprecated: Please use GetModifiers() - instead! - @true if shift is pressed down. - */ - - - /** - int m_x - @b Deprecated: Please use GetX() instead! - X position of the event. - */ - - - /** - int m_y - @b Deprecated: Please use GetY() instead! - Y position of the event. + Notice that GetModifiers() is easier to use correctly than this function + so you should consider using it in new code. */ + bool ShiftDown() const; }; @@ -256,9 +229,22 @@ public: @class wxJoystickEvent @wxheader{event.h} - This event class contains information about mouse events, particularly + This event class contains information about joystick events, particularly events received by windows. + @beginEventTable{wxJoystickEvent} + @style{EVT_JOY_BUTTON_DOWN(func)}: + Process a wxEVT_JOY_BUTTON_DOWN event. + @style{EVT_JOY_BUTTON_UP(func)}: + Process a wxEVT_JOY_BUTTON_UP event. + @style{EVT_JOY_MOVE(func)}: + Process a wxEVT_JOY_MOVE event. + @style{EVT_JOY_ZMOVE(func)}: + Process a wxEVT_JOY_ZMOVE event. + @style{EVT_JOYSTICK_EVENTS(func)}: + Processes all joystick events. + @endEventTable + @library{wxcore} @category{events} @@ -270,16 +256,16 @@ public: /** Constructor. */ - wxJoystickEvent(wxEventType eventType = 0, int state = 0, + wxJoystickEvent(wxEventType eventType = wxEVT_NULL, int state = 0, int joystick = wxJOYSTICK1, int change = 0); /** - Returns @true if the event was a down event from the specified button (or any - button). + Returns @true if the event was a down event from the specified button + (or any button). @param button - Can be wxJOY_BUTTONn where n is 1, 2, 3 or 4; or wxJOY_BUTTON_ANY to + Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to indicate any button down event. */ bool ButtonDown(int button = wxJOY_BUTTON_ANY) const; @@ -288,32 +274,32 @@ public: Returns @true if the specified button (or any button) was in a down state. @param button - Can be wxJOY_BUTTONn where n is 1, 2, 3 or 4; or wxJOY_BUTTON_ANY to + Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to indicate any button down event. */ bool ButtonIsDown(int button = wxJOY_BUTTON_ANY) const; /** - Returns @true if the event was an up event from the specified button (or any - button). + Returns @true if the event was an up event from the specified button + (or any button). @param button - Can be wxJOY_BUTTONn where n is 1, 2, 3 or 4; or wxJOY_BUTTON_ANY to + Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to indicate any button down event. */ bool ButtonUp(int button = wxJOY_BUTTON_ANY) const; /** - Returns the identifier of the button changing state. This is a wxJOY_BUTTONn - identifier, where - n is one of 1, 2, 3, 4. + Returns the identifier of the button changing state. + + This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4. */ int GetButtonChange() const; /** - Returns the down state of the buttons. This is a bitlist of wxJOY_BUTTONn - identifiers, where - n is one of 1, 2, 3, 4. + Returns the down state of the buttons. + + This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4. */ int GetButtonState() const; @@ -334,8 +320,8 @@ public: int GetZPosition() const; /** - Returns @true if this was a button up or down event (@e not 'is any button - down?'). + Returns @true if this was a button up or down event + (@e not 'is any button down?'). */ bool IsButton() const; @@ -358,10 +344,36 @@ public: A scroll event holds information about events sent from scrolling windows. + + @beginEventTable{wxScrollWinEvent} + You can use the EVT_SCROLLWIN* macros for intercepting scroll window events + from the receiving window. + @event{EVT_SCROLLWIN(func)}: + Process all scroll events. + @event{EVT_SCROLLWIN_TOP(func)}: + Process wxEVT_SCROLLWIN_TOP scroll-to-top events. + @event{EVT_SCROLLWIN_BOTTOM(func)}: + Process wxEVT_SCROLLWIN_BOTTOM scroll-to-bottom events. + @event{EVT_SCROLLWIN_LINEUP(func)}: + Process wxEVT_SCROLLWIN_LINEUP line up events. + @event{EVT_SCROLLWIN_LINEDOWN(func)}: + Process wxEVT_SCROLLWIN_LINEDOWN line down events. + @event{EVT_SCROLLWIN_PAGEUP(func)}: + Process wxEVT_SCROLLWIN_PAGEUP page up events. + @event{EVT_SCROLLWIN_PAGEDOWN(func)}: + Process wxEVT_SCROLLWIN_PAGEDOWN page down events. + @event{EVT_SCROLLWIN_THUMBTRACK(func)}: + Process wxEVT_SCROLLWIN_THUMBTRACK thumbtrack events + (frequent events sent as the user drags the thumbtrack). + @event{EVT_SCROLLWIN_THUMBRELEASE(func)}: + Process wxEVT_SCROLLWIN_THUMBRELEASE thumb release events. + @endEventTable + + @library{wxcore} @category{events} - @see wxScrollEvent, @ref overview_eventhandlingoverview + @see wxScrollEvent, @ref overview_eventhandling */ class wxScrollWinEvent : public wxEvent { @@ -369,17 +381,20 @@ public: /** Constructor. */ - wxScrollWinEvent(wxEventType commandType = 0, int pos = 0, + wxScrollWinEvent(wxEventType commandType = wxEVT_NULL, int pos = 0, int orientation = 0); /** Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the scrollbar. + + @todo wxHORIZONTAL and wxVERTICAL should go in their own enum */ int GetOrientation() const; /** Returns the position of the scrollbar for the thumb track and release events. + Note that this field can't be used for the other events, you need to query the window itself for the current position in that case. */ @@ -396,10 +411,21 @@ public: when the user changes the colour settings using the control panel. This is only appropriate under Windows. + @remarks + The default event handler for this event propagates the event to child windows, + since Windows only sends the events to top-level windows. + If intercepting this event for a top-level window, remember to call the base + class handler, or to pass the event on to the window's children explicitly. + + @beginEventTable{wxSysColourChangedEvent} + @event{EVT_SYS_COLOUR_CHANGED(func)}: + Process a wxEVT_SYS_COLOUR_CHANGED event. + @endEventTable + @library{wxcore} @category{events} - @see @ref overview_eventhandlingoverview + @see @ref overview_eventhandling */ class wxSysColourChangedEvent : public wxEvent { @@ -417,15 +443,20 @@ public: @wxheader{event.h} This event is sent just after the actual window associated with a wxWindow - object - has been created. Since it is derived from wxCommandEvent, the event propagates - up + object has been created. + + Since it is derived from wxCommandEvent, the event propagates up the window hierarchy. + @beginEventTable{wxWindowCreateEvent} + @event{EVT_WINDOW_CREATE(func)}: + Process a wxEVT_CREATE event. + @endEventTable + @library{wxcore} @category{events} - @see @ref overview_eventhandlingoverview, wxWindowDestroyEvent + @see @ref overview_eventhandling, wxWindowDestroyEvent */ class wxWindowCreateEvent : public wxCommandEvent { @@ -445,14 +476,69 @@ public: A paint event is sent when a window's contents needs to be repainted. Please notice that in general it is impossible to change the drawing of a - standard control (such as wxButton) and so you shouldn't - attempt to handle paint events for them as even if it might work on some - platforms, this is inherently not portable and won't work everywhere. + standard control (such as wxButton) and so you shouldn't attempt to handle + paint events for them as even if it might work on some platforms, this is + inherently not portable and won't work everywhere. + + @remarks + Note that in a paint event handler, the application must always create a + wxPaintDC object, even if you do not use it. Otherwise, under MS Windows, + refreshing for this and other windows will go wrong. + For example: + @code + void MyWindow::OnPaint(wxPaintEvent& event) + { + wxPaintDC dc(this); + + DrawMyDocument(dc); + } + @endcode + You can optimize painting by retrieving the rectangles that have been damaged + and only repainting these. The rectangles are in terms of the client area, + and are unscrolled, so you will need to do some calculations using the current + view position to obtain logical, scrolled units. + Here is an example of using the wxRegionIterator class: + @code + // Called when window needs to be repainted. + void MyWindow::OnPaint(wxPaintEvent& event) + { + wxPaintDC dc(this); + + // Find Out where the window is scrolled to + int vbX,vbY; // Top left corner of client + GetViewStart(&vbX,&vbY); + + int vX,vY,vW,vH; // Dimensions of client area in pixels + wxRegionIterator upd(GetUpdateRegion()); // get the update rect list + + while (upd) + { + vX = upd.GetX(); + vY = upd.GetY(); + vW = upd.GetW(); + vH = upd.GetH(); + + // Alternatively we can do this: + // wxRect rect(upd.GetRect()); + + // Repaint this rectangle + ...some code... + + upd ++ ; + } + } + @endcode + + + @beginEventTable{wxPaintEvent} + @event{EVT_PAINT(func)}: + Process a wxEVT_PAINT event. + @endEventTable @library{wxcore} @category{events} - @see @ref overview_eventhandlingoverview + @see @ref overview_eventhandling */ class wxPaintEvent : public wxEvent { @@ -471,14 +557,18 @@ public: An event being sent when a top level window is maximized. Notice that it is not sent when the window is restored to its original size after it had been - maximized, only a normal wxSizeEvent is generated in - this case. + maximized, only a normal wxSizeEvent is generated in this case. + + @beginEventTable{wxMaximizeEvent} + @event{EVT_MAXIMIZE(func)}: + Process a wxEVT_MAXIMIZE event. + @endEventTable @library{wxcore} @category{events} - @see @ref overview_eventhandlingoverview, wxTopLevelWindow::Maximize, - wxTopLevelWindow::IsMaximized + @see @ref overview_eventhandling, wxTopLevelWindow::Maximize, + wxTopLevelWindow::IsMaximized */ class wxMaximizeEvent : public wxEvent { @@ -498,10 +588,51 @@ public: This class is used for pseudo-events which are called by wxWidgets to give an application the chance to update various user interface elements. + @remarks + Without update UI events, an application has to work hard to check/uncheck, + enable/disable, show/hide, and set the text for elements such as menu items + and toolbar buttons. The code for doing this has to be mixed up with the code + that is invoked when an action is invoked for a menu item or button. + With update UI events, you define an event handler to look at the state of the + application and change UI elements accordingly. wxWidgets will call your member + functions in idle time, so you don't have to worry where to call this code. + In addition to being a clearer and more declarative method, it also means you don't + have to worry whether you're updating a toolbar or menubar identifier. The same + handler can update a menu item and toolbar button, if the identifier is the same. + Instead of directly manipulating the menu or button, you call functions in the event + object, such as wxUpdateUIEvent::Check. wxWidgets will determine whether such a + call has been made, and which UI element to update. + These events will work for popup menus as well as menubars. Just before a menu is + popped up, wxMenu::UpdateUI is called to process any UI events for the window that + owns the menu. + If you find that the overhead of UI update processing is affecting your application, + you can do one or both of the following: + @li Call wxUpdateUIEvent::SetMode with a value of wxUPDATE_UI_PROCESS_SPECIFIED, + and set the extra style wxWS_EX_PROCESS_UI_UPDATES for every window that should + receive update events. No other windows will receive update events. + @li Call wxUpdateUIEvent::SetUpdateInterval with a millisecond value to set the delay + between updates. You may need to call wxWindow::UpdateWindowUI at critical points, + for example when a dialog is about to be shown, in case the user sees a slight + delay before windows are updated. + Note that although events are sent in idle time, defining a wxIdleEvent handler + for a window does not affect this because the events are sent from wxWindow::OnInternalIdle + which is always called in idle time. + wxWidgets tries to optimize update events on some platforms. + On Windows and GTK+, events for menubar items are only sent when the menu is about + to be shown, and not in idle time. + + @beginEventTable{wxUpdateUIEvent} + @event{EVT_UPDATE_UI(id, func)}: + Process a wxEVT_UPDATE_UI event for the command with the given id. + @event{EVT_UPDATE_UI_RANGE(id1, id2, func)}: + Process a wxEVT_UPDATE_UI event for any command with id included in the given range. + @endEventTable + + @library{wxcore} @category{events} - @see @ref overview_eventhandlingoverview + @see @ref overview_eventhandling */ class wxUpdateUIEvent : public wxCommandEvent { @@ -665,7 +796,7 @@ public: makes it possible to only process the latter if it doesn't matter if the text was copied or cut. - @beginEventTable + @beginEventTable{wxClipboardTextEvent} @event{EVT_TEXT_COPY(id, func)}: Some or all of the controls content was copied to the clipboard. @event{EVT_TEXT_CUT(id, func)}: @@ -717,14 +848,14 @@ public: parent window receives @c wxEVT_LEAVE_WINDOW event not only when the mouse leaves the window entirely but also when it enters one of its children. - @b NB: Note that under Windows CE mouse enter and leave events are not natively + @note Note that under Windows CE mouse enter and leave events are not natively supported by the system but are generated by wxWidgets itself. This has several drawbacks: the LEAVE_WINDOW event might be received some time after the mouse left the window and the state variables for it may have changed during this time. - @b NB: Note the difference between methods like + @note Note the difference between methods like wxMouseEvent::LeftDown and wxMouseEvent::LeftIsDown: the former returns @true when the event corresponds to the left mouse button click while the latter @@ -1171,7 +1302,7 @@ public: @library{wxcore} @category{events} - @see @ref overview_eventhandlingoverview + @see @ref overview_eventhandling */ class wxDropFilesEvent : public wxEvent { @@ -1343,7 +1474,7 @@ public: @library{wxcore} @category{events} - @see @ref overview_eventhandlingoverview, wxApp::IsActive + @see @ref overview_eventhandling, wxApp::IsActive */ class wxActivateEvent : public wxEvent { @@ -1385,7 +1516,7 @@ public: @category{events} @see @ref overview_wxcommandevent "Command events", @ref - overview_eventhandlingoverview + overview_eventhandling */ class wxContextMenuEvent : public wxCommandEvent { @@ -1437,7 +1568,7 @@ public: @library{wxcore} @category{events} - @see @ref overview_eventhandlingoverview + @see @ref overview_eventhandling */ class wxEraseEvent : public wxEvent { @@ -1470,7 +1601,7 @@ public: @library{wxcore} @category{events} - @see @ref overview_eventhandlingoverview + @see @ref overview_eventhandling */ class wxFocusEvent : public wxEvent { @@ -1505,7 +1636,7 @@ public: @library{wxcore} @category{events} - @see @ref overview_eventhandlingoverview + @see @ref overview_eventhandling */ class wxChildFocusEvent : public wxCommandEvent { @@ -1546,7 +1677,7 @@ public: @library{wxcore} @category{events} - @see wxMouseCaptureChangedEvent, @ref overview_eventhandlingoverview, + @see wxMouseCaptureChangedEvent, @ref overview_eventhandling, wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture */ class wxMouseCaptureLostEvent : public wxEvent @@ -1635,9 +1766,9 @@ public: since processing would stop after the first window found. @library{wxcore} - @category{FIXME} + @category{events} - @see wxContextHelp, wxDialog, @ref overview_eventhandlingoverview + @see wxContextHelp, wxDialog, @ref overview_eventhandling */ class wxHelpEvent : public wxCommandEvent { @@ -1720,7 +1851,7 @@ public: @category{events} @see wxScrollBar, wxSlider, wxSpinButton, , wxScrollWinEvent, @ref - overview_eventhandlingoverview + overview_eventhandling */ class wxScrollEvent : public wxCommandEvent { @@ -1769,7 +1900,7 @@ public: @library{wxbase} @category{events} - @see @ref overview_eventhandlingoverview, wxUpdateUIEvent, + @see @ref overview_eventhandling, wxUpdateUIEvent, wxWindow::OnInternalIdle */ class wxIdleEvent : public wxEvent @@ -1849,7 +1980,7 @@ public: @library{wxcore} @category{events} - @see @ref overview_eventhandlingoverview + @see @ref overview_eventhandling */ class wxInitDialogEvent : public wxEvent { @@ -1882,7 +2013,7 @@ public: @library{wxcore} @category{events} - @see @ref overview_eventhandlingoverview, wxWindowCreateEvent + @see @ref overview_eventhandling, wxWindowCreateEvent */ class wxWindowDestroyEvent : public wxCommandEvent { @@ -1990,7 +2121,7 @@ public: @library{wxcore} @category{events} - @see wxMouseCaptureLostEvent, @ref overview_eventhandlingoverview, + @see wxMouseCaptureLostEvent, @ref overview_eventhandling, wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture */ class wxMouseCaptureChangedEvent : public wxEvent @@ -2105,7 +2236,7 @@ public: @category{events} @see @ref overview_wxcommandevent "Command events", @ref - overview_eventhandlingoverview + overview_eventhandling */ class wxMenuEvent : public wxEvent { @@ -2163,9 +2294,9 @@ public: @endcode @library{wxcore} - @category{FIXME} + @category{events} - @see @ref overview_eventhandlingoverview, wxEvtHandler + @see @ref overview_eventhandling, wxEvtHandler */ class wxEventBlocker : public wxEvtHandler { @@ -2210,9 +2341,9 @@ public: will be identical to the "this" pointer for the wxEvtHandler portion. @library{wxbase} - @category{FIXME} + @category{events} - @see @ref overview_eventhandlingoverview + @see @ref overview_eventhandling */ class wxEvtHandler : public wxObject { @@ -2495,7 +2626,7 @@ public: @library{wxcore} @category{events} - @see @ref overview_eventhandlingoverview, wxTopLevelWindow::Iconize, + @see @ref overview_eventhandling, wxTopLevelWindow::Iconize, wxTopLevelWindow::IsIconized */ class wxIconizeEvent : public wxEvent @@ -2524,7 +2655,7 @@ public: @library{wxcore} @category{events} - @see wxPoint, @ref overview_eventhandlingoverview + @see wxPoint, @ref overview_eventhandling */ class wxMoveEvent : public wxEvent { @@ -2550,7 +2681,7 @@ public: callback or member function. @b wxEvent used to be a multipurpose event object, and is an abstract base class for other event classes (see below). - For more information about events, see the @ref overview_eventhandlingoverview. + For more information about events, see the @ref overview_eventhandling. @b wxPerl note: In wxPerl custom event classes should be derived from @c Wx::PlEvent and @c Wx::PlCommandEvent. @@ -2718,7 +2849,7 @@ public: @library{wxcore} @category{events} - @see wxSize, @ref overview_eventhandlingoverview + @see wxSize, @ref overview_eventhandling */ class wxSizeEvent : public wxEvent { @@ -2747,7 +2878,7 @@ public: specify the cursor you want to be displayed. @library{wxcore} - @category{FIXME} + @category{events} @see ::wxSetCursor, wxWindow::wxSetCursor */ diff --git a/interface/file.h b/interface/file.h index 412af0a40b..7ece7ce26e 100644 --- a/interface/file.h +++ b/interface/file.h @@ -165,7 +165,7 @@ public: /** Destructor will close the file. - @b NB: it is not virtual so you should not use wxFile polymorphically. + @note it is not virtual so you should not use wxFile polymorphically. */ ~wxFile(); diff --git a/interface/list.h b/interface/list.h index 3d491d35b3..ea950dbd09 100644 --- a/interface/list.h +++ b/interface/list.h @@ -140,12 +140,12 @@ public: wxListT::compatibility_iterator Item(size_t index) const; /** - @b NB: This function is deprecated, use wxList::Find instead. + @note This function is deprecated, use wxList::Find instead. */ wxListT::compatibility_iterator Member(T* object) const; /** - @b NB: This function is deprecated, use @ref wxList::itemfunc Item instead. + @note This function is deprecated, use @ref wxList::itemfunc Item instead. Returns the @e nth node in the list, indexing from zero (@NULL if the list is empty or the nth node could not be found). @@ -153,7 +153,7 @@ public: wxListT::compatibility_iterator Nth(int n) const; /** - @b NB: This function is deprecated, use wxList::GetCount instead. + @note This function is deprecated, use wxList::GetCount instead. Returns the number of elements in the list. */ int Number() const; diff --git a/interface/listbox.h b/interface/listbox.h index 69602ffb64..73ea54d0d4 100644 --- a/interface/listbox.h +++ b/interface/listbox.h @@ -43,7 +43,7 @@ The listbox contents are sorted in alphabetical order. @endStyleTable - @beginEventTable + @beginEventTable{wxCommandEvent} @event{EVT_LISTBOX(id, func)}: Process a wxEVT_COMMAND_LISTBOX_SELECTED event, when an item on the list is selected or the selection changes. diff --git a/interface/listctrl.h b/interface/listctrl.h index af512023c0..4af80810f1 100644 --- a/interface/listctrl.h +++ b/interface/listctrl.h @@ -179,7 +179,7 @@ public: /** Deletes all items in the list control. - @b NB: This function does @e not send the + @note This function does @e not send the @c wxEVT_COMMAND_LIST_DELETE_ITEM event because deleting many items from the control would be too slow then (unlike wxListCtrl::DeleteItem). */ @@ -275,7 +275,7 @@ public: /** Returns the edit control being currently used to edit a label. Returns @NULL if no label is being edited. - @b NB: It is currently only implemented for wxMSW and the generic version, + @note It is currently only implemented for wxMSW and the generic version, not for the native Mac OS X version. */ wxTextCtrl* GetEditControl() const; @@ -399,7 +399,7 @@ public: Searches for an item to the right of the specified item. - @b NB: this parameter is only supported by wxMSW currently and ignored on + @note this parameter is only supported by wxMSW currently and ignored on other platforms. @a state can be a bitlist of the following: @@ -628,7 +628,7 @@ public: @a dx specifies the number of pixels to scroll. If in list view mode, @a dx specifies the number of columns to scroll. @a dy always specifies the number of pixels to scroll vertically. - @b NB: This method is currently only implemented in the Windows version. + @note This method is currently only implemented in the Windows version. */ bool ScrollList(int dx, int dy); diff --git a/interface/log.h b/interface/log.h index d19674a90d..3292edb5f8 100644 --- a/interface/log.h +++ b/interface/log.h @@ -436,7 +436,7 @@ public: "[%d/%b/%y %H:%M:%S] " which gives something like "[17/Sep/98 22:10:16] " (without quotes) for the current date. Setting an empty string as the time format disables timestamping of the messages completely. - @b NB: Timestamping is disabled for Visual C++ users in debug builds by + @note Timestamping is disabled for Visual C++ users in debug builds by default because otherwise it would be impossible to directly go to the line from which the log message was generated by simply clicking in the debugger window on the corresponding error message. If you wish to enable it, please use diff --git a/interface/menu.h b/interface/menu.h index 97baeef519..bfc5f442ff 100644 --- a/interface/menu.h +++ b/interface/menu.h @@ -357,7 +357,7 @@ public: with a special identifier -1 is a separator item and doesn't have an associated command but just makes a separator line appear in the menu. - @b NB: Please note that @e wxID_ABOUT and @e wxID_EXIT are + @note Please note that @e wxID_ABOUT and @e wxID_EXIT are predefined by wxWidgets and have a special meaning since entries using these IDs will be taken out of the normal menus under MacOS X and will be inserted into the system menu (following the appropriate diff --git a/interface/menuitem.h b/interface/menuitem.h index b652a0621f..e8604c2a53 100644 --- a/interface/menuitem.h +++ b/interface/menuitem.h @@ -172,7 +172,7 @@ public: /** Returns the text associated with the menu item. - @b NB: this function is deprecated, please use + @note this function is deprecated, please use GetItemLabel() or GetItemLabelText() instead. */ diff --git a/interface/notebook.h b/interface/notebook.h index 43a91dc98c..f71444eb3b 100644 --- a/interface/notebook.h +++ b/interface/notebook.h @@ -48,7 +48,7 @@ public: /** Returns the currently selected page, or -1 if none was selected. - @b NB: under Windows, GetSelection() will return the same value as + @note under Windows, GetSelection() will return the same value as GetOldSelection() when called from @c EVT_NOTEBOOK_PAGE_CHANGING handler and not the page which is going to be selected. Also note that the values of selection and old selection returned @@ -391,7 +391,7 @@ public: /** Sets the amount of space around each page's icon and label, in pixels. - @b NB: The vertical padding cannot be changed in wxGTK. + @note The vertical padding cannot be changed in wxGTK. */ void SetPadding(const wxSize& padding); @@ -403,7 +403,7 @@ public: /** Sets the width and height of the pages. - @b NB: This method is currently not implemented for wxGTK. + @note This method is currently not implemented for wxGTK. */ virtual void SetPageSize(const wxSize& size); diff --git a/interface/odcombo.h b/interface/odcombo.h index 3661b82530..ecd545f67a 100644 --- a/interface/odcombo.h +++ b/interface/odcombo.h @@ -30,7 +30,7 @@ painted unless SetCustomPaintWidth is called. @endStyleTable - @beginEventTable + @beginEventTable{wxCommandEvent} @event{EVT_COMBOBOX(id, func)}: Process a wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on the list is selected. Note that calling GetValue returns the new diff --git a/interface/radiobox.h b/interface/radiobox.h index a3be1145e4..c86fe2235c 100644 --- a/interface/radiobox.h +++ b/interface/radiobox.h @@ -25,7 +25,7 @@ supported only on PalmOS) @endStyleTable - @beginEventTable + @beginEventTable{wxCommandEvent} @event{EVT_RADIOBOX(id, func)}: Process a wxEVT_COMMAND_RADIOBOX_SELECTED event, when a radiobutton is clicked. @@ -35,7 +35,7 @@ @category{ctrl} @appearance{radiobox.png} - @see @ref overview_eventhandlingoverview, wxRadioButton, wxCheckBox + @see @ref overview_eventhandling, wxRadioButton, wxCheckBox */ class wxRadioBox : public wxControlWithItems { diff --git a/interface/radiobut.h b/interface/radiobut.h index 1dc741718f..04b58e60b8 100644 --- a/interface/radiobut.h +++ b/interface/radiobut.h @@ -31,7 +31,7 @@ only on PalmOS). @endStyleTable - @beginEventTable + @beginEventTable{wxCommandEvent} @event{EVT_RADIOBUTTON(id, func)}: Process a wxEVT_COMMAND_RADIOBUTTON_SELECTED event, when the radiobutton is clicked. @@ -41,7 +41,7 @@ @category{ctrl} @appearance{radiobutton.png} - @see @ref overview_eventhandlingoverview, wxRadioBox, wxCheckBox + @see @ref overview_eventhandling, wxRadioBox, wxCheckBox */ class wxRadioButton : public wxControl { diff --git a/interface/sashwin.h b/interface/sashwin.h index 5ad783ad87..8baad97cd4 100644 --- a/interface/sashwin.h +++ b/interface/sashwin.h @@ -28,7 +28,7 @@ Draws a thin black border. @endStyleTable - @beginEventTable + @beginEventTable{wxSashEvent} @event{EVT_SASH_DRAGGED(id, func)}: Process a wxEVT_SASH_DRAGGED event, when the user has finished dragging a sash. @@ -41,7 +41,7 @@ @library{wxadv} @category{miscwnd} - @see wxSashEvent, wxSashLayoutWindow, @ref overview_eventhandlingoverview + @see wxSashEvent, wxSashLayoutWindow, @ref overview_eventhandling */ class wxSashWindow : public wxWindow { diff --git a/interface/spinbutt.h b/interface/spinbutt.h index 3c990bfbb3..5bd9f8ae9f 100644 --- a/interface/spinbutt.h +++ b/interface/spinbutt.h @@ -49,7 +49,7 @@ public: as wxSpinButton is not implemented for all platforms but wxSpinCtrl is as it degenerates to a simple wxTextCtrl on such platforms. - @b NB: the range supported by this control (and wxSpinCtrl) depends on the + @note the range supported by this control (and wxSpinCtrl) depends on the platform but is at least @c -0x8000 to @c 0x7fff. Under GTK and Win32 with sufficiently new version of @c comctrl32.dll (at least 4.71 is required, 5.80 is recommended) the full 32 bit range is supported. diff --git a/interface/spinctrl.h b/interface/spinctrl.h index bdbd4f6aa9..046c98ccd2 100644 --- a/interface/spinctrl.h +++ b/interface/spinctrl.h @@ -106,7 +106,7 @@ public: Select the text in the text part of the control between positions @a from (inclusive) and @a to (exclusive). This is similar to wxTextCtrl::SetSelection. - @b NB: this is currently only implemented for Windows and generic versions + @note this is currently only implemented for Windows and generic versions of the control. */ void SetSelection(long from, long to); diff --git a/interface/string.h b/interface/string.h index 4441581d90..8076a9652b 100644 --- a/interface/string.h +++ b/interface/string.h @@ -658,7 +658,7 @@ public: Note that if @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function supports Unix98-style positional parameters: - @b NB: This function will use a safe version of @e vsprintf() (usually called + @note This function will use a safe version of @e vsprintf() (usually called @e vsnprintf()) whenever available to always allocate the buffer of correct size. Unfortunately, this function is not available on all platforms and the dangerous @e vsprintf() will be used then which may lead to buffer overflows. diff --git a/interface/textctrl.h b/interface/textctrl.h index 65cbd6e747..fa9f057773 100644 --- a/interface/textctrl.h +++ b/interface/textctrl.h @@ -1339,7 +1339,7 @@ public: This class can be used to (temporarily) redirect all output sent to a C++ ostream object to a wxTextCtrl instead. - @b NB: Some compilers and/or build configurations don't support multiply + @note Some compilers and/or build configurations don't support multiply inheriting wxTextCtrl from @c std::streambuf in which case this class is not compiled in. You also must have @c wxUSE_STD_IOSTREAM option on (i.e. set to 1) in your setup.h to be able to use it. Under Unix, diff --git a/interface/tglbtn.h b/interface/tglbtn.h index 9a31b188c5..0ee09ceded 100644 --- a/interface/tglbtn.h +++ b/interface/tglbtn.h @@ -20,7 +20,7 @@ You can see wxToggleButton in action in the sixth page of the controls() sample. - @beginEventTable + @beginEventTable{wxCommandEvent} @event{EVT_TOGGLEBUTTON(id, func)}: Handles a toggle button click event. @endEventTable @@ -113,7 +113,7 @@ public: This control emits an update UI event. - @beginEventTable + @beginEventTable{wxCommandEvent} @event{EVT_TOGGLEBUTTON(id, func)}: Handles a toggle button click event. @endEventTable diff --git a/interface/treectrl.h b/interface/treectrl.h index e1f8bb474d..f4bff505a8 100644 --- a/interface/treectrl.h +++ b/interface/treectrl.h @@ -357,7 +357,7 @@ public: /** Returns the edit control being currently used to edit a label. Returns @NULL if no label is being edited. - @b NB: It is currently only implemented for wxMSW. + @note It is currently only implemented for wxMSW. */ wxTextCtrl* GetEditControl() const; diff --git a/interface/txtstrm.h b/interface/txtstrm.h index 90597ebcdf..7a126a3a1e 100644 --- a/interface/txtstrm.h +++ b/interface/txtstrm.h @@ -140,7 +140,7 @@ public: wxString ReadLine(); /** - @b NB: This method is deprecated, use ReadLine() + @note This method is deprecated, use ReadLine() or ReadWord() instead. Same as ReadLine(). */ diff --git a/interface/window.h b/interface/window.h index 8b2f9d4097..ab5670b7da 100644 --- a/interface/window.h +++ b/interface/window.h @@ -2596,7 +2596,7 @@ public: /** Moves the pointer to the given position on the window. - @b NB: This function is not supported under Mac because Apple Human + @note This function is not supported under Mac because Apple Human Interface Guidelines forbid moving the mouse cursor programmatically. @param x -- 2.45.2