From 3ed3a1c846d66410872a15f746c432311e306e42 Mon Sep 17 00:00:00 2001 From: Bryan Petty Date: Sun, 4 May 2008 09:04:38 +0000 Subject: [PATCH] Initial review of various [q-r] by Utensil Candel. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53444 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/doxygen/mainpages/platdetails.h | 66 ++++---- docs/doxygen/overviews/printing.h | 6 +- docs/doxygen/overviews/python.h | 33 ++-- docs/doxygen/overviews/refcount.h | 13 +- docs/doxygen/regen.bat | 6 +- interface/quantize.h | 34 ++-- interface/radiobox.h | 189 +++++++++++++---------- interface/radiobut.h | 33 ++-- interface/rawbmp.h | 222 ++++++++++++++------------- interface/recguard.h | 43 +++--- interface/regex.h | 156 +++++++++++++++---- 11 files changed, 476 insertions(+), 325 deletions(-) diff --git a/docs/doxygen/mainpages/platdetails.h b/docs/doxygen/mainpages/platdetails.h index 7506f3d3a5..a4f9161133 100644 --- a/docs/doxygen/mainpages/platdetails.h +++ b/docs/doxygen/mainpages/platdetails.h @@ -189,7 +189,7 @@ in the distribution. @subsection page_port_wxmsw_themedborders Themed borders on Windows -Starting with wxWidgets 2.8.5, you can specify the wxBORDER_THEME style to have wxWidgets +Starting with wxWidgets 2.8.5, you can specify the @c wxBORDER_THEME style to have wxWidgets use a themed border. Using the default XP theme, this is a thin 1-pixel blue border, with an extra 1-pixel border in the window client background colour (usually white) to separate the client area's scrollbars from the border. @@ -198,11 +198,11 @@ If you don't specify a border style for a wxTextCtrl in rich edit mode, wxWidget the control themed borders automatically, where previously they would take the Windows 95-style sunken border. Other native controls such as wxTextCtrl in non-rich edit mode, and wxComboBox, already paint themed borders where appropriate. To use themed borders on other windows, such -as wxPanel, pass the wxBORDER_THEME style, or (apart from wxPanel) pass no border style. +as wxPanel, pass the @c wxBORDER_THEME style, or (apart from wxPanel) pass no border style. -In general, specifying wxBORDER_THEME will cause a border of some kind to be used, chosen by the platform -and control class. To leave the border decision entirely to wxWidgets, pass wxBORDER_DEFAULT. -This is not to be confused with specifying wxBORDER_NONE, which says that there should +In general, specifying @c wxBORDER_THEME will cause a border of some kind to be used, chosen by the platform +and control class. To leave the border decision entirely to wxWidgets, pass @c wxBORDER_DEFAULT. +This is not to be confused with specifying @c wxBORDER_NONE, which says that there should definitely be @e no border. @subsubsection page_port_wxmsw_themedborders_details More detail on border implementation @@ -241,7 +241,7 @@ of listboxes where appropriate. You also need to reduce the amount of spacing used by sizers, for which you can use a macro such as this: -@verbatim +@code #if defined(__WXWINCE__) #define wxLARGESMALL(large,small) small #else @@ -250,7 +250,7 @@ use a macro such as this: // Usage topsizer->Add( CreateTextSizer( message ), 0, wxALL, wxLARGESMALL(10,0) ); -@endverbatim +@endcode There is only ever one instance of a Windows CE application running, and wxWidgets will take care of showing the current instance and @@ -306,7 +306,7 @@ If the screen orientation changes, the windows will automatically be resized so no further action needs to be taken (unless you want to change the layout according to the orientation, which you could detect in idle time, for example). When input panel (SIP) is shown, top level windows (frames and dialogs) resize -accordingly (see wxTopLevelWindow::HandleSettingChange). +accordingly (see wxTopLevelWindow::HandleSettingChange()). @subsubsection page_port_wxmsw_wince_toplevel Closing top-level windows in wxWinCE @@ -316,24 +316,24 @@ event to force the application to close down. @subsubsection page_port_wxmsw_wince_hibernation Hibernation in wxWinCE -Smartphone and PocketPC will send a wxEVT_HIBERNATE to the application object in low +Smartphone and PocketPC will send a @c wxEVT_HIBERNATE to the application object in low memory conditions. Your application should release memory and close dialogs, -and wake up again when the next wxEVT_ACTIVATE or wxEVT_ACTIVATE_APP message is received. -(wxEVT_ACTIVATE_APP is generated whenever a wxEVT_ACTIVATE event is received -in Smartphone and PocketPC, since these platforms do not support WM_ACTIVATEAPP.) +and wake up again when the next @c wxEVT_ACTIVATE or @c wxEVT_ACTIVATE_APP message is received. +(@c wxEVT_ACTIVATE_APP is generated whenever a @c wxEVT_ACTIVATE event is received +in Smartphone and PocketPC, since these platforms do not support @c WM_ACTIVATEAPP.) @subsubsection page_port_wxmsw_wince_hwbutt Hardware buttons in wxWinCE -Special hardware buttons are sent to a window via the wxEVT_HOTKEY event +Special hardware buttons are sent to a window via the @c wxEVT_HOTKEY event under Smartphone and PocketPC. You should first register each required button with -wxWindow::RegisterHotKey, and unregister the button when you're done with it. For example: +wxWindow::RegisterHotKey(), and unregister the button when you're done with it. For example: -@verbatim +@code win->RegisterHotKey(0, wxMOD_WIN, WXK_SPECIAL1); win->UnregisterHotKey(0); -@endverbatim +@endcode -You may have to register the buttons in a wxEVT_ACTIVATE event handler +You may have to register the buttons in a @c wxEVT_ACTIVATE event handler since other applications will grab the buttons. There is currently no method of finding out the names of the special @@ -345,15 +345,15 @@ PocketPC dialogs have an OK button on the caption, and so you should generally not repeat an OK button on the dialog. You can add a Cancel button if necessary, but some dialogs simply don't offer you the choice (the guidelines recommend you offer an Undo facility to make up for it). When the user clicks on the OK button, your dialog will receive -a wxID_OK event by default. If you wish to change this, call wxDialog::SetAffirmativeId -with the required identifier to be used. Or, override wxDialog::DoOK (return @false to +a @c wxID_OK event by default. If you wish to change this, call wxDialog::SetAffirmativeId() +with the required identifier to be used. Or, override wxDialog::DoOK() (return @false to have wxWidgets simply call Close to dismiss the dialog). Smartphone dialogs do @e not have an OK button on the caption, and are closed using one of the two menu buttons. You need to assign these using wxTopLevelWindow::SetLeftMenu -and wxTopLevelWindow::SetRightMenu, for example: +and wxTopLevelWindow::SetRightMenu(), for example: -@verbatim +@code #ifdef __SMARTPHONE__ SetLeftMenu(wxID_OK); SetRightMenu(wxID_CANCEL, _("Cancel")); @@ -362,9 +362,9 @@ and wxTopLevelWindow::SetRightMenu, for example: #else topsizer->Add( CreateButtonSizer( wxOK|wxCANCEL ), 0, wxEXPAND | wxALL, 10 ); #endif -@endverbatim +@endcode -For implementing property sheets (flat tabs), use a wxNotebook with wxNB_FLAT|wxNB_BOTTOM +For implementing property sheets (flat tabs), use a wxNotebook with @c wxNB_FLAT|wxNB_BOTTOM and have the notebook left, top and right sides overlap the dialog by about 3 pixels to eliminate spurious borders. You can do this by using a negative spacing in your sizer Add() call. The cross-platform property sheet dialog wxPropertySheetDialog is @@ -387,7 +387,7 @@ Menubars and toolbars are implemented using a combined control, but you can use essentially the usual wxWidgets API; wxWidgets will combine the menubar and toolbar. However, there are some restrictions: -@li You must create the frame's primary toolbar with wxFrame::CreateToolBar, +@li You must create the frame's primary toolbar with wxFrame::CreateToolBar(), because this uses the special wxToolMenuBar class (derived from wxToolBar) to implement the combined toolbar and menubar. Otherwise, you can create and manage toolbars using the wxToolBar class as usual, for example to implement an optional @@ -402,8 +402,8 @@ or with transparency (for example, using XPMs). controls. Unlike in all other ports, a wxDialog has a wxToolBar, automatically created -for you. You may either leave it blank, or access it with wxDialog::GetToolBar -and add buttons, then calling wxToolBar::Realize. You cannot set or recreate +for you. You may either leave it blank, or access it with wxDialog::GetToolBar() +and add buttons, then calling wxToolBar::Realize(). You cannot set or recreate the toolbar. @subsubsection page_port_wxmsw_wince_smart Menubars and toolbars in Smartphone @@ -424,7 +424,7 @@ wxID_EXIT, it will do the right thing. @subsubsection page_port_wxmsw_wince_ctx Context menus in wxWinCE -To enable context menus in PocketPC, you currently need to call wxWindow::EnableContextMenu, +To enable context menus in PocketPC, you currently need to call wxWindow::EnableContextMenu(), a wxWinCE-only function. Otherwise the context menu event (wxContextMenuEvent) will never be sent. This API is subject to change. @@ -434,7 +434,7 @@ Context menus are not supported in Smartphone. These controls and styles are specific to wxWinCE: -@li wxTextCtrl The wxTE_CAPITALIZE style causes a CAPEDIT control to +@li wxTextCtrl The @c wxTE_CAPITALIZE style causes a CAPEDIT control to be created, which capitalizes the first letter. These controls are missing from wxWinCE: @@ -447,9 +447,9 @@ tooltips are distinct controls, and it will be hard to add dynamic tooltip support. Control borders on PocketPC and Smartphone should normally be specified with -wxBORDER_SIMPLE instead of wxBORDER_SUNKEN. Controls will usually adapt +@c wxBORDER_SIMPLE instead of @c wxBORDER_SUNKEN. Controls will usually adapt appropriately by virtue of their GetDefaultBorder() function, but if you -wish to specify a style explicitly you can use wxDEFAULT_CONTROL_BORDER +wish to specify a style explicitly you can use @c wxDEFAULT_CONTROL_BORDER which will give a simple border on PocketPC and Smartphone, and the sunken border on other platforms. @@ -569,11 +569,11 @@ icons, should be implemented. This will be quite straightforward. and the remaining area, by calling SHSipInfo. We also may need to be able to show and hide the SIP programmatically, with SHSipPreference. See also the Input Dialogs topic in the Programming Windows CE guide for more on this, and how to have dialogs -show the SIP automatically using the WC_SIPREF control. +show the SIP automatically using the @c WC_SIPREF control. @li wxStaticBitmap. The About box in the "Life!" demo shows a bitmap that is the correct size on the emulator, but too small on a VGA Pocket Loox device. @li wxStaticLine. Lines don't show up, and the documentation suggests that -missing styles are implemented with WM_PAINT. +missing styles are implemented with @c WM_PAINT. @li HTML control. PocketPC has its own HTML control which can be used for showing local pages or navigating the web. We should create a version of wxHtmlWindow that uses this control, or have a separately-named control (wxHtmlCtrl), with a syntax as close as possible @@ -587,7 +587,7 @@ between controls. The focus handling in wxWidgets needs investigation. See in pa src/common/containr.cpp, and note that the default OnActivate handler in src/msw/toplevel.cpp sets the focus to the first child of the dialog. @li OK button. We should allow the OK button on a dialog to be optional, perhaps -by using wxCLOSE_BOX to indicate when the OK button should be displayed. +by using @c wxCLOSE_BOX to indicate when the OK button should be displayed. @li Dynamic adaptation. We should probably be using run-time tests more than preprocessor tests, so that the same WinCE application can run on different versions of the operating system. diff --git a/docs/doxygen/overviews/printing.h b/docs/doxygen/overviews/printing.h index 02076df1fa..6026fa7e6e 100644 --- a/docs/doxygen/overviews/printing.h +++ b/docs/doxygen/overviews/printing.h @@ -97,7 +97,7 @@ printing under MSW and Mac), or a wxPostScriptDC (for printing under GTK or generating PostScript output). The @ref overview_docview "document/view framework" creates a default -wxPrintout object for every view, calling wxView::OnDraw to achieve a +wxPrintout object for every view, calling wxView::OnDraw() to achieve a prepackaged print/preview facility. If your window classes have a Draw(wxDC *dc) routine to do screen rendering, @@ -141,7 +141,7 @@ There are two important rectangles in printing: the page rectangle defines the printable area seen by the application, and under MSW and Mac, it is the printable area specified by the printer. (For PostScript printing, the page rectangle is the entire page.) The inherited function -wxDC::GetSize returns the page size in device pixels. The +wxDC::GetSize() returns the page size in device pixels. The point (0,0) on the wxPrinterDC represents the top left corner of the page rectangle; that is, the page rect is given by wxRect(0, 0, w, h), where (w,h) are the values returned by GetSize. @@ -150,7 +150,7 @@ The paper rectangle, on the other hand, represents the entire paper area including the non-printable border. Thus, the coordinates of the top left corner of the paper rectangle will have small negative values, while the width and height will be somewhat larger than that of the page rectangle. The -wxPrinterDC-specific function wxPrinterDC::GetPaperRect returns the paper +wxPrinterDC-specific function wxPrinterDC::GetPaperRect() returns the paper rectangle of the given wxPrinterDC. diff --git a/docs/doxygen/overviews/python.h b/docs/doxygen/overviews/python.h index b269a69188..e738a656ac 100644 --- a/docs/doxygen/overviews/python.h +++ b/docs/doxygen/overviews/python.h @@ -10,7 +10,8 @@ @page overview_python wxPython Overview -This topic was written by Robin Dunn, author of the wxPython wrapper. +This topic was written by Robin Dunn, author of the +wxPython wrapper. @li @ref overview_python_what @li @ref overview_python_why @@ -120,19 +121,19 @@ pieces you need without having to use the GUI portions. There are quite a few other GUI modules available for Python, some in active use, some that haven't been updated for ages. Most are simple wrappers around some C or C++ toolkit or another, and most are not cross-platform compatible. -See http://pypi.python.org/pypi?:action=browse&show=all&c=433 for a listing of -a few of them. +See this link +for a listing of a few of them. @section overview_python_using Using wxPython I'm not going to try and teach the Python language here. You can do that at the -. I'm also going to assume that you -know a bit about wxWidgets already, enough to notice the similarities in the -classes used. +Python Tutorial. I'm also +going to assume that you know a bit about wxWidgets already, enough to notice +the similarities in the classes used. Take a look at the following wxPython program. You can find a similar program -in the wxPython/demo directory, named "DialogUnits.py". If your Python and +in the @c wxPython/demo directory, named @c DialogUnits.py. If your Python and wxPython are properly installed, you should be able to run it by issuing this command: @@ -221,8 +222,8 @@ python DialogUnits.py At line 2 the wxPython classes, constants, and etc. are imported into the current module's namespace. If you prefer to reduce namespace pollution you can -use "from wxPython import wx" and then access all the wxPython identifiers -through the wx module, for example, "wx.wxFrame". +use @c "from wxPython import wx" and then access all the wxPython identifiers +through the wx module, for example, @c "wx.wxFrame". At line 13 the frame's sizing and moving events are connected to methods of the class. These helper functions are intended to be like the event table macros @@ -235,13 +236,13 @@ Notice the use of @c wxDLG_PNT and @c wxDLG_SZE in lines 19-29 to convert from dialog units to pixels. These helpers are unique to wxPython since Python can't do method overloading like C++. -There is an @c OnCloseWindow method at line 34 but no call to EVT_CLOSE to +There is an @c OnCloseWindow method at line 34 but no call to @c EVT_CLOSE to attach the event to the method. Does it really get called? The answer is, yes it does. This is because many of the standard events are attached to windows that have the associated standard method names. I have tried to follow the lead of the C++ classes in this area to determine what is standard but since that changes from time to time I can make no guarantees, nor will it be fully -documented. When in doubt, use an EVT_*** function. +documented. When in doubt, use an @c EVT_*** function. At lines 17 to 21 notice that there are no saved references to the panel or the static text items that are created. Those of you who know Python might be @@ -250,7 +251,7 @@ scope. Do they disappear from the GUI? They don't. Remember that in wxPython the Python objects are just shadows of the corresponding C++ objects. Once the C++ windows and controls are attached to their parents, the parents manage them and delete them when necessary. For this reason, most wxPython objects do not -need to have a __del__ method that explicitly causes the C++ object to be +need to have a @c __del__ method that explicitly causes the C++ object to be deleted. If you ever have the need to forcibly delete a window, use the Destroy() method as shown on line 36. @@ -300,7 +301,7 @@ spec over time. @li wxColour @li wxComboBox @li wxCommandEvent -@li wxConfig +@li wxConfigBase @li wxControl @li wxCursor @li wxCustomDataObject @@ -355,7 +356,7 @@ spec over time. @li wxIndividualLayoutConstraint @li wxInitDialogEvent @li wxInputStream -@li wxInternetFSHandler +@li @ref wxFileSystem "wxInternetFSHandler" @li wxJoystickEvent @li wxJPEGHandler @li wxKeyEvent @@ -377,7 +378,7 @@ spec over time. @li wxMenuItem @li wxMenu @li wxMessageDialog -@li wxMetaFileDC +@li wxMetafileDC @li wxMiniFrame @li wxMouseEvent @li wxMoveEvent @@ -454,7 +455,7 @@ spec over time. @li wxValidator @li wxWindowDC @li wxWindow -@li wxZipFSHandler +@li @ref wxFileSystem "wxZipFSHandler" @section overview_python_help Where to Go for Help diff --git a/docs/doxygen/overviews/refcount.h b/docs/doxygen/overviews/refcount.h index 48a2bf1bb7..75454a80c3 100644 --- a/docs/doxygen/overviews/refcount.h +++ b/docs/doxygen/overviews/refcount.h @@ -41,9 +41,10 @@ operation on it is the same. @section overview_refcount_equality Object Comparison -The == and != operators of the reference counted classes always do a @c deep -comparison. This means that the equality operator will return @true if two -objects are identical and not only if they share the same data. +The == and != operators of @ref overview_refcount_list "the reference counted classes" +always do a deep comparison. This means that the equality operator +will return @true if two objects are identical and not only if they share the +same data. Note that wxWidgets follows the STL philosophy: when a comparison operator can not be implemented efficiently (like for e.g. wxImage's == @@ -90,8 +91,8 @@ operators and copy constructors since they are reference-counted: Note that the list above reports the objects which are reference counted in all ports of wxWidgets; some ports may use this technique also for other classes. -All the objects implement a function IsOk() to test if they are referencing valid -data; when the objects are in uninitialized state, you can only use the IsOk() getter; +All the objects implement a function @b IsOk() to test if they are referencing valid +data; when the objects are in uninitialized state, you can only use the @b IsOk() getter; trying to call any other getter, e.g. wxBrush::GetStyle() on the ::wxNullBrush object, will result in an assert failure in debug builds. @@ -120,7 +121,7 @@ In fact, any time you need to read the data from your wxObject-derived class, you will need to call this function. @note Any time you need to actually modify the data placed inside your wxObject -derived class, you must first call the wxObject::UnShare function to ensure +derived class, you must first call the wxObject::UnShare() function to ensure that the modifications won't affect other instances which are eventually sharing your object's data. diff --git a/docs/doxygen/regen.bat b/docs/doxygen/regen.bat index e3bfd0a54d..c70350b8a0 100644 --- a/docs/doxygen/regen.bat +++ b/docs/doxygen/regen.bat @@ -15,9 +15,9 @@ REM These not automatically copied by Doxygen because it's not REM used in doxygen documentation, only in our html footer. copy images\powered-by-wxwidgets.png out\html 2>&1 >NUL copy images\*logo.png out\html 2>&1 >NUL -copy images\wxgtk\*png out\html\wxgtk 2>&1 >NUL -copy images\wxmsw\*png out\html\wxmsw 2>&1 >NUL -copy images\wxmac\*png out\html\wxmac 2>&1 >NUL +copy images\wxgtk\*.png out\html\wxgtk 2>&1 >NUL +copy images\wxmsw\*.png out\html\wxmsw 2>&1 >NUL +copy images\wxmac\*.png out\html\wxmac 2>&1 >NUL copy wxwidgets.js out\html 2>&1 >NUL REM this CSS is automatically copied by Doxygen because it's diff --git a/interface/quantize.h b/interface/quantize.h index 4ba79d58a7..eeea5bcad9 100644 --- a/interface/quantize.h +++ b/interface/quantize.h @@ -29,30 +29,38 @@ public: /** Converts input bitmap(s) into 8bit representation with custom palette. - in_rows and out_rows are arrays [0..h-1] of pointer to rows - (in_rows contains w * 3 bytes per row, out_rows w bytes per row). - Fills out_rows with indexes into palette (which is also stored into palette + @a in_rows and @a out_rows are arrays [0..h-1] of pointer to rows + (@a in_rows contains @a w * 3 bytes per row, @a out_rows @a w bytes per row). + Fills @a out_rows with indexes into palette (which is also stored into @a palette variable). */ void DoQuantize(unsigned w, unsigned h, unsigned char** in_rows, - unsigned char** out_rows, - unsigned char* palette, + unsigned char** out_rows, unsigned char* palette, int desiredNoColours); - //@{ /** - This version sets a palette in the destination image so you don't - have to manage it yourself. + Reduce the colours in the source image and put the result into the destination image. + Both images may be the same, to overwrite the source image. + + Specify an optional palette pointer to receive the resulting palette. + This palette may be passed to ConvertImageToBitmap, for example. */ bool Quantize(const wxImage& src, wxImage& dest, - wxPalette** pPalette, - int desiredNoColours = 236, + wxPalette** pPalette, int desiredNoColours = 236, unsigned char** eightBitData = 0, - int flags = wxQUANTIZE_INCLUDE_WINDOWS_COLOURS|wxQUANTIZE_FILL_DESTINATION_IMAGE|wxQUANTIZE_RETURN_8BIT_DATA); + int flags = wxQUANTIZE_INCLUDE_WINDOWS_COLOURS + |wxQUANTIZE_FILL_DESTINATION_IMAGE + |wxQUANTIZE_RETURN_8BIT_DATA); + + /** + This version sets a palette in the destination image so you don't + have to manage it yourself. + */ bool Quantize(const wxImage& src, wxImage& dest, int desiredNoColours = 236, unsigned char** eightBitData = 0, - int flags = wxQUANTIZE_INCLUDE_WINDOWS_COLOURS|wxQUANTIZE_FILL_DESTINATION_IMAGE|wxQUANTIZE_RETURN_8BIT_DATA); - //@} + int flags = wxQUANTIZE_INCLUDE_WINDOWS_COLOURS + |wxQUANTIZE_FILL_DESTINATION_IMAGE + |wxQUANTIZE_RETURN_8BIT_DATA); }; diff --git a/interface/radiobox.h b/interface/radiobox.h index 143e0b800f..2aeb3772fa 100644 --- a/interface/radiobox.h +++ b/interface/radiobox.h @@ -27,7 +27,7 @@ @beginEventTable{wxCommandEvent} @event{EVT_RADIOBOX(id, func)} - Process a wxEVT_COMMAND_RADIOBOX_SELECTED event, when a radiobutton + Process a @c wxEVT_COMMAND_RADIOBOX_SELECTED event, when a radiobutton is clicked. @endEventTable @@ -40,30 +40,37 @@ class wxRadioBox : public wxControl, wxItemContainerImmutable { public: - //@{ + + /** + Default constructor. + + @see Create(), wxValidator + */ + wxRadioBox(); + /** Constructor, creating and showing a radiobox. @param parent Parent window. Must not be @NULL. @param id - Window identifier. The value wxID_ANY indicates a default value. + Window identifier. The value @c wxID_ANY indicates a default value. @param label Label for the static box surrounding the radio buttons. @param pos - Window position. If wxDefaultPosition is specified then a default - position is chosen. + Window position. If @c wxDefaultPosition is specified then a + default position is chosen. @param size - Window size. If wxDefaultSize is specified then a default size - is chosen. + Window size. If @c wxDefaultSize is specified then a default size + is chosen. @param n Number of choices with which to initialize the radiobox. @param choices An array of choices with which to initialize the radiobox. @param majorDimension - Specifies the maximum number of rows (if style contains wxRA_SPECIFY_ROWS) - or columns (if style contains wxRA_SPECIFY_COLS) for a two-dimensional - radiobox. + 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. @param style Window style. See wxRadioBox. @param validator @@ -73,10 +80,9 @@ public: @see Create(), wxValidator */ - wxRadioBox(); wxRadioBox(wxWindow* parent, wxWindowID id, const wxString& label, - const wxPoint& point = wxDefaultPosition, + const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, int n = 0, const wxString choices[] = NULL, @@ -84,30 +90,59 @@ public: long style = wxRA_SPECIFY_COLS, const wxValidator& validator = wxDefaultValidator, const wxString& name = "radioBox"); + + /** + Constructor, creating and showing a radiobox. + + @param parent + Parent window. Must not be @NULL. + @param id + Window identifier. The value @c wxID_ANY indicates a default value. + @param label + Label for the static box surrounding the radio buttons. + @param pos + Window position. If @c wxDefaultPosition is specified then a + default position is chosen. + @param size + Window size. If @c wxDefaultSize is specified then a default size + is chosen. + @param choices + An array of choices with which to initialize the radiobox. + @param majorDimension + 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. + @param style + Window style. See wxRadioBox. + @param validator + Window validator. + @param name + Window name. + + @see Create(), wxValidator + */ wxRadioBox(wxWindow* parent, wxWindowID id, const wxString& label, - const wxPoint& point, + const wxPoint& pos, const wxSize& size, const wxArrayString& choices, int majorDimension = 0, long style = wxRA_SPECIFY_COLS, const wxValidator& validator = wxDefaultValidator, const wxString& name = "radioBox"); - //@} /** Destructor, destroying the radiobox item. */ ~wxRadioBox(); - //@{ /** Creates the radiobox for two-step construction. See wxRadioBox() for further details. */ bool Create(wxWindow* parent, wxWindowID id, const wxString& label, - const wxPoint& point = wxDefaultPosition, + const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, int n = 0, const wxString choices[] = NULL, @@ -115,18 +150,21 @@ public: long style = wxRA_SPECIFY_COLS, const wxValidator& validator = wxDefaultValidator, const wxString& name = "radioBox"); + + /** + Creates the radiobox for two-step construction. See wxRadioBox() + for further details. + */ bool Create(wxWindow* parent, wxWindowID id, const wxString& label, - const wxPoint& point, + const wxPoint& pos, const wxSize& size, const wxArrayString& choices, int majorDimension = 0, long style = wxRA_SPECIFY_COLS, const wxValidator& validator = wxDefaultValidator, const wxString& name = "radioBox"); - //@} - //@{ /** Enables or disables an individual button in the radiobox. @@ -135,11 +173,20 @@ public: @param n The zero-based button to enable or disable. - @see wxWindow::Enable + @see wxWindow::Enable() + + @beginWxPythonOnly + In place of a single overloaded method name, wxPython implements the following methods: + + @beginTable + @row2col{Enable(flag), Enables or disables the entire radiobox.} + @row2col{EnableItem(n\, flag), Enables or disables an individual button in the radiobox.} + @endTable + + @endWxPythonOnly */ - virtual bool Enable(bool enable = true); virtual bool Enable(unsigned int n, bool enable = true); - //@} + /** Finds a button matching the given string, returning the position if found, or @@ -178,48 +225,21 @@ public: /** Returns the tooltip associated with the specified @a item if any or @NULL. - @see SetItemToolTip(), wxWindow::GetToolTip + @see SetItemToolTip(), wxWindow::GetToolTip() */ wxToolTip* GetItemToolTip(unsigned int item) const; - /** - Returns the radiobox label. - - @param n - The zero-based button index. - - @see SetLabel() - */ - wxString GetLabel() const; - /** Returns the number of rows in the radiobox. */ unsigned int GetRowCount() const; - /** - Returns the zero-based position of the selected button. - */ - int GetSelection() const; - - /** - Returns the label for the button at the given position. - - @param n - The zero-based button position. - */ - wxString GetString(unsigned int n) const; - - /** - Returns the selected string. - */ - wxString GetStringSelection() const; - /** Returns @true if the item is enabled or @false if it was disabled using - @ref enable() "Enable(n, @false)". - @b Platform note: Currently only implemented in wxMSW, wxGTK and wxUniversal - and always returns @true in the other ports. + @ref Enable(unsigned int,bool) "Enable(n, false)". + + This function is currently only implemented in wxMSW, wxGTK and + wxUniversal and always returns @true in the other ports. @param n The zero-based button position. @@ -228,13 +248,13 @@ public: /** Returns @true if the item is currently shown or @false if it was hidden - using - @ref show() "Show(n, @false)". + using @ref Show(unsigned int,bool) "Show(n, false)". + Note that this function returns @true for an item which hadn't been hidden - even - if the entire radiobox is not currently shown. - @b Platform note: Currently only implemented in wxMSW, wxGTK and wxUniversal - and always returns @true in the other ports. + even if the entire radiobox is not currently shown. + + This function is currently only implemented in wxMSW, wxGTK and + wxUniversal and always returns @true in the other ports. @param n The zero-based button position. @@ -255,45 +275,44 @@ public: /** Sets the tooltip text for the specified item in the radio group. - @b Platform note: Currently only implemented in wxMSW and wxGTK2 and does - nothing in the other ports. + + This function is currently only implemented in wxMSW and wxGTK2 and + does nothing in the other ports. @param item Index of the item the tooltip will be shown for. @param text Tooltip text for the item, the tooltip is removed if empty. - @see GetItemToolTip(), wxWindow::SetToolTip + @see GetItemToolTip(), wxWindow::SetToolTip() */ void SetItemToolTip(unsigned int item, const wxString& text); /** - Sets the radiobox label. + Shows or hides individual buttons. - @param label - The label to set. - @param n - The zero-based button index. - */ - void SetLabel(const wxString& label); + @param show + @true to show, @false to hide. + @param item + The zero-based position of the button to show or hide. - /** - Sets a button by passing the desired string position. This does not cause - a wxEVT_COMMAND_RADIOBOX_SELECTED event to get emitted. + @return + @true if the item has been shown or hidden or @false if nothing + was done because it already was in the requested state. - @param n - The zero-based button position. - */ - void SetSelection(int n); + @see + wxWindow::Show() - /** - Sets the selection to a button by passing the desired string. This does not - cause - a wxEVT_COMMAND_RADIOBOX_SELECTED event to get emitted. + @beginWxPythonOnly + In place of a single overloaded method name, wxPython implements the following methods: + + @beginTable + @row2col{Show(flag), Shows or hides the entire radiobox.} + @row2col{ShowItem(n\, flag), Shows or hides individual buttons.} + @endTable + + @endWxPythonOnly - @param string - The label of the button to select. */ - void SetStringSelection(const wxString& string); + virtual bool Show(unsigned int item, const bool show = true); }; - diff --git a/interface/radiobut.h b/interface/radiobut.h index 11d32f510e..dfce977c50 100644 --- a/interface/radiobut.h +++ b/interface/radiobut.h @@ -10,13 +10,13 @@ @class wxRadioButton @wxheader{radiobut.h} - A radio button item is a button which usually denotes one of several mutually - exclusive options. It has a text label next to a (usually) round button. + A radio button item is a button which usually denotes one of several + mutually exclusive options. It has a text label next to a (usually) round + button. - You can create a group of mutually-exclusive radio buttons by specifying @c - wxRB_GROUP for - the first in the group. The group ends when another radio button group is - created, or there are no more radio buttons. + You can create a group of mutually-exclusive radio buttons by specifying + @c wxRB_GROUP for the first in the group. The group ends when another + radio button group is created, or there are no more radio buttons. @beginStyleTable @style{wxRB_GROUP} @@ -33,7 +33,7 @@ @beginEventTable{wxCommandEvent} @event{EVT_RADIOBUTTON(id, func)} - Process a wxEVT_COMMAND_RADIOBUTTON_SELECTED event, when the + Process a @c wxEVT_COMMAND_RADIOBUTTON_SELECTED event, when the radiobutton is clicked. @endEventTable @@ -46,21 +46,28 @@ class wxRadioButton : public wxControl { public: - //@{ + + /** + Default constructor. + + @see Create(), wxValidator + */ + wxRadioButton(); + /** Constructor, creating and showing a radio button. @param parent Parent window. Must not be @NULL. @param id - Window identifier. The value wxID_ANY indicates a default value. + Window identifier. The value @c wxID_ANY indicates a default value. @param label Label for the radio button. @param pos - Window position. If wxDefaultPosition is specified then a default + Window position. If @c wxDefaultPosition is specified then a default position is chosen. @param size - Window size. If wxDefaultSize is specified then a default size + Window size. If @c wxDefaultSize is specified then a default size is chosen. @param style Window style. See wxRadioButton. @@ -71,7 +78,6 @@ public: @see Create(), wxValidator */ - wxRadioButton(); wxRadioButton(wxWindow* parent, wxWindowID id, const wxString& label, const wxPoint& pos = wxDefaultPosition, @@ -79,7 +85,6 @@ public: long style = 0, const wxValidator& validator = wxDefaultValidator, const wxString& name = "radioButton"); - //@} /** Destructor, destroying the radio button item. @@ -105,7 +110,7 @@ public: /** Sets the radio button to selected or deselected status. This does not cause a - wxEVT_COMMAND_RADIOBUTTON_SELECTED event to get emitted. + @c wxEVT_COMMAND_RADIOBUTTON_SELECTED event to get emitted. @param value @true to select, @false to deselect. diff --git a/interface/rawbmp.h b/interface/rawbmp.h index 7dc4f7a38e..df9ac84567 100644 --- a/interface/rawbmp.h +++ b/interface/rawbmp.h @@ -1,3 +1,10 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: rawbmp.h +// Purpose: interface of wxPixelData +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// /** @class wxPixelData @@ -8,14 +15,19 @@ wxImage's internal data through a standard interface. It is possible to extend this class (interface) to other types of image content. - + Implemented on Windows, GTK+ and OS X: - @li wxNativePixelData: Class to access to wxBitmap's internal data without alpha channel (RGB). - @li wxAlphaPixelData: Class to access to wxBitmap's internal data with alpha channel (RGBA). - + @li wxNativePixelData: Class to access to wxBitmap's internal data + without alpha channel (RGB). + @li wxAlphaPixelData: Class to access to wxBitmap's internal data with + alpha channel (RGBA). + Implemented everywhere: - @li wxImagePixelData: Class to access to wxImage's internal data with alpha channel (RGBA). - + @li wxImagePixelData: Class to access to wxImage's internal data with + alpha channel (RGBA). + + Example: + @code wxBitmap bmp; wxNativePixelData data(bmp); @@ -54,7 +66,7 @@ @library{wxcore} @category{gdi} - + @see wxBitmap, wxImage */ template > @@ -62,140 +74,142 @@ class wxPixelData : public wxPixelDataOut::template wxPixelDataIn { public: - /** - the type of the class we're working with + /** + The type of the class we're working with. */ typedef Image ImageType; - + /** - Create pixel data object representing the entire image + Create pixel data object representing the entire image. */ wxPixelData(Image& image); - - + + /** - Create pixel data object representing the area - of the image defined by @e rect. + Create pixel data object representing the area of the image defined by + @a rect. */ wxPixelData(Image& i, const wxRect& rect); - + /** - Create pixel data object representing the area - of the image defined by @e pt and @e sz. + Create pixel data object representing the area of the image defined by + @a pt and @a sz. */ wxPixelData(Image& i, const wxPoint& pt, const wxSize& sz) - + /** - Return true of if we could get access to bitmap data - successfully + Return @true of if we could get access to bitmap data successfully. */ operator bool() const: - /** - Return the iterator pointing to the origin of the image + /** + Return the iterator pointing to the origin of the image. */ Iterator GetPixels() const; /** - Returns origin of the rectangular region we represent + Returns origin of the rectangular region this wxPixelData represents. */ wxPoint GetOrigin() const; - /** - Return width of the region we represent + /** + Return width of the region this wxPixelData represents. */ int GetWidth() const; - /** - Return height of the region we represent + /** + Return height of the region this wxPixelData represents. */ int GetHeight() const; - /* - Return area which this class represents in the image + /** + Return the area which this wxPixelData represents in the image. */ wxSize GetSize() const; /** - Return the distance between two rows + Return the distance between two rows. */ int GetRowStride() const; /** - Iterator + The iterator of class wxPixelData. */ - class Iterator - { - public: - /** - go back to (0, 0) - */ - void Reset(const PixelData& data); - - /** - Initializes the iterator to point to the origin of the given - pixel data - */ - Iterator(PixelData& data); - - /** - Initializes the iterator to point to the origin of the given - Bitmap - */ - Iterator(wxBitmap& bmp, PixelData& data); - - /** - Default constructor - */ - Iterator(); - - /** - Return true if this iterator is valid - */ - bool IsOk() const; - - /** - Advance the iterator to the next pixel, prefix version - */ - Iterator& operator++(); - - /** - Postfix (hence less efficient -- don't use it unless you - absolutely must) version - */ - Iterator operator++(int); - - /** - Move x pixels to the right and y down - note that the rows don't wrap! - */ - void Offset(const PixelData& data, int x, int y); - - /** - Move x pixels to the right (again, no row wrapping) - */ - void OffsetX(const PixelData&data, int x); - - /** - Move y rows to the bottom - */ - void OffsetY(const PixelData& data, int y); - - /** - Go to the given position - */ - void MoveTo(const PixelData& data, int x, int y); - - //@{ - /** - Data access: gives access to invidividual colour components. - */ - ChannelType& Red(); - ChannelType& Green(); - ChannelType& Blue(); - ChannelType& Alpha(); - //@} - }; + class Iterator + { + public: + + /** + Reset the iterator to point to (0, 0). + */ + void Reset(const PixelData& data); + + /** + Initializes the iterator to point to the origin of the given pixel + data. + */ + Iterator(PixelData& data); + + /** + Initializes the iterator to point to the origin of the given Bitmap. + */ + Iterator(wxBitmap& bmp, PixelData& data); + + /** + Default constructor. + */ + Iterator(); + + /** + Return @true if this iterator is valid. + */ + bool IsOk() const; + + /** + Advance the iterator to the next pixel, prefix version. + */ + Iterator& operator++(); + + /** + Advance the iterator to the next pixel, postfix (hence less + efficient -- don't use it unless you absolutely must) version. + */ + Iterator operator++(int); + + /** + Move @a x pixels to the right and @a y down. + + @note The rows won't wrap automatically. + */ + void Offset(const PixelData& data, int x, int y); + + /** + Move @a x pixels to the right. + + @note The rows won't wrap automatically. + */ + void OffsetX(const PixelData&data, int x); + + /** + Move @a y rows to the bottom + */ + void OffsetY(const PixelData& data, int y); + + /** + Go to the given position + */ + void MoveTo(const PixelData& data, int x, int y); + + //@{ + /** + Data Access: Access to invidividual colour components. + */ + ChannelType& Red(); + ChannelType& Green(); + ChannelType& Blue(); + ChannelType& Alpha(); + //@} + }; }; diff --git a/interface/recguard.h b/interface/recguard.h index 89cda8df07..748fcc7608 100644 --- a/interface/recguard.h +++ b/interface/recguard.h @@ -11,11 +11,12 @@ @wxheader{recguard.h} This is a completely opaque class which exists only to be used with - wxRecursionGuard, please see the example in that - class documentation. + wxRecursionGuard, please see the example in that class' documentation. - Please notice that wxRecursionGuardFlag object must be declared - @c static or the recursion would never be detected. + @remarks + + wxRecursionGuardFlag object must be declared @c static or the recursion + would never be detected. @library{wxbase} @category{FIXME} @@ -42,22 +43,22 @@ public: @code void Foo() + { + static wxRecursionGuardFlag s_flag; + wxRecursionGuard guard(s_flag); + if ( guard.IsInside() ) { - static wxRecursionGuardFlag s_flag; - wxRecursionGuard guard(s_flag); - if ( guard.IsInside() ) - { - // don't allow reentrancy - return; - } - - ... + // don't allow reentrancy + return; } + + ... + } @endcode As you can see, wxRecursionGuard simply tests the flag value and sets it to @true if it hadn't been already set. - wxRecursionGuard::IsInside allows testing the old flag + IsInside() allows testing the old flag value. The advantage of using this class compared to directly manipulating the flag is that the flag is always reset in the wxRecursionGuard destructor and so you don't risk to forget to do it even if the function returns in an unexpected @@ -70,7 +71,7 @@ class wxRecursionGuard { public: /** - A wxRecursionGuard object must always be initialized with a (static) + A wxRecursionGuard object must always be initialized with a @c static wxRecursionGuardFlag. The constructor saves the value of the flag to be able to return the correct value from IsInside(). @@ -80,16 +81,18 @@ public: /** The destructor resets the flag value so that the function can be entered again the next time. - Note that it is not virtual and so this class is not meant to be derived from - (besides, there is absolutely no reason to do it anyhow). + + @note This is not virtual, so this class is not meant to be derived + from (besides, there is absolutely no reason to do it anyhow). */ ~wxRecursionGuard(); /** Returns @true if we're already inside the code block "protected" by this - wxRecursionGuard (i.e. between this line and the end of current scope). Usually - the function using wxRecursionGuard takes some specific actions in such case - (may be simply returning) to prevent reentrant calls to itself. + wxRecursionGuard (i.e. between this line and the end of current scope). + Usually the function using wxRecursionGuard takes some specific actions + in such case (may be simply returning) to prevent reentrant calls to itself. + If this method returns @false, it is safe to continue. */ bool IsInside() const; diff --git a/interface/regex.h b/interface/regex.h index 68db15b112..d7c1b0f197 100644 --- a/interface/regex.h +++ b/interface/regex.h @@ -6,6 +6,51 @@ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// +/** + Flags for regex compilation to be used with Compile(). +*/ +enum +{ + /** Use extended regex syntax. */ + wxRE_EXTENDED = 0, + + /** Use advanced RE syntax (built-in regex only). */ + wxRE_ADVANCED = 1, + + /** Use basic RE syntax. */ + wxRE_BASIC = 2, + + /** Ignore case in match. */ + wxRE_ICASE = 4, + + /** Only check match, don't set back references. */ + wxRE_NOSUB = 8, + + /** + If not set, treat '\n' as an ordinary character, otherwise it is + special: it is not matched by '.' and '^' and '$' always match + after/before it regardless of the setting of wxRE_NOT[BE]OL. + */ + wxRE_NEWLINE = 16, + + /** Default flags.*/ + wxRE_DEFAULT = wxRE_EXTENDED +}; + +/** + Flags for regex matching to be used with Matches(). + These flags are mainly useful when doing several matches in a long string + to prevent erroneous matches for ¡¯¡¯ and ¡¯$¡¯: +*/ +enum +{ + /** '^' doesn't match at the start of line. */ + wxRE_NOTBOL = 32, + + /** '$' doesn't match at the end of line. */ + wxRE_NOTEOL = 64 +}; + /** @class wxRegEx @wxheader{regex.h} @@ -21,7 +66,7 @@ Regular expressions, as defined by POSIX, come in two flavours: @e extended and @e basic. The builtin library also adds a third flavour - of expression advanced(), which is not available + of expression @ref overview_resyntax "advanced", which is not available when using the system library. Unicode is fully supported only when using the builtin library. @@ -37,49 +82,87 @@ @library{wxbase} @category{data} - @see wxRegEx::ReplaceFirst + Examples: + + A bad example of processing some text containing email addresses (the example + is bad because the real email addresses can have more complicated form than + @c user@host.net): + + @code + wxString text; + ... + wxRegEx reEmail = wxT("([^@]+)@([[:alnum:].-_].)+([[:alnum:]]+)"); + if ( reEmail.Matches(text) ) + { + wxString text = reEmail.GetMatch(email); + wxString username = reEmail.GetMatch(email, 1); + if ( reEmail.GetMatch(email, 3) == wxT("com") ) // .com TLD? + { + ... + } + } + + // or we could do this to hide the email address + size_t count = reEmail.ReplaceAll(text, wxT("HIDDEN@\\2\\3")); + printf("text now contains %u hidden addresses", count); + @endcode */ class wxRegEx { public: - //@{ + + /** + Default constructor: use Compile() later. + */ + wxRegEx(); + /** Create and compile the regular expression, use IsValid() to test for compilation errors. + + @todo Add referece to the flag enum. */ - wxRegEx(); wxRegEx(const wxString& expr, int flags = wxRE_DEFAULT); - //@} + /** - dtor not virtual, don't derive from this class + Destructor. It's not virtual, don't derive from this class. */ ~wxRegEx(); /** Compile the string into regular expression, return @true if ok or @false if string has a syntax error. + + @todo Add referece to the flag enum. */ bool Compile(const wxString& pattern, int flags = wxRE_DEFAULT); - //@{ /** - Returns the part of string corresponding to the match where @a index is - interpreted as above. Empty string is returned if match failed - May only be called after successful call to Matches() - and only if @c wxRE_NOSUB was @b not used in - Compile(). + Get the start index and the length of the match of the expression + (if @a index is 0) or a bracketed subexpression (@a index different from 0). + + May only be called after successful call to Matches() and only if @c wxRE_NOSUB + was @b not used in Compile(). + + Returns @false if no match or if an error occurred. + */ bool GetMatch(size_t* start, size_t* len, size_t index = 0) const; - const not used in - Compile(). - Returns false if no match or if an error occurred. - wxString GetMatch(const wxString& text, size_t index = 0) const; - //@} + + /** + Returns the part of string corresponding to the match where index is interpreted + as above. Empty string is returned if match failed. + + May only be called after successful call to Matches() and only if @c wxRE_NOSUB + was @b not used in Compile(). + */ + wxString GetMatch(const wxString& text, size_t index = 0) const; /** Returns the size of the array of matches, i.e. the number of bracketed subexpressions plus one for the expression itself, or 0 on error. + May only be called after successful call to Compile(). and only if @c wxRE_NOSUB was @b not used. */ @@ -93,32 +176,49 @@ public: //@{ /** - Matches the precompiled regular expression against the string @e text, + Matches the precompiled regular expression against the string @a text, returns @true if matches and @false otherwise. + @e Flags may be combination of @c wxRE_NOTBOL and @c wxRE_NOTEOL. + @todo Add referece to the flag enum. + Some regex libraries assume that the text given is null terminated, while others require the length be given as a separate parameter. Therefore for maximum portability assume that @a text cannot contain embedded nulls. - When the @e Matches(const wxChar *text, int flags = 0) form is used, - a @e wxStrlen() will be done internally if the regex library requires the - length. When using @e Matches() in a loop - the @e Matches(text, flags, len) form can be used instead, making it - possible to avoid a @e wxStrlen() inside the loop. + + When the Matches(const wxChar *text, int flags = 0) form is used, + a wxStrlen() will be done internally if the regex library requires the + length. When using Matches() in a loop the Matches(text, flags, len) + form can be used instead, making it possible to avoid a wxStrlen() inside + the loop. + May only be called after successful call to Compile(). */ bool Matches(const wxChar* text, int flags = 0) const; const bool Matches(const wxChar* text, int flags, size_t len) const; - const bool Matches(const wxString& text, int flags = 0) const; //@} + /** + Matches the precompiled regular expression against the string @a text, + returns @true if matches and @false otherwise. + + @e Flags may be combination of @c wxRE_NOTBOL and @c wxRE_NOTEOL. + @todo Add referece to the flag enum. + + May only be called after successful call to Compile(). + */ + const bool Matches(const wxString& text, int flags = 0) const; + /** Replaces the current regular expression in the string pointed to by - @e text, with the text in @a replacement and return number of matches + @a text, with the text in @a replacement and return number of matches replaced (maybe 0 if none found) or -1 on error. - The replacement text may contain back references @c \number which will be + + The replacement text may contain back references @c \\number which will be replaced with the value of the corresponding subexpression in the - pattern match. @c \0 corresponds to the entire match and @c is a - synonym for it. Backslash may be used to quote itself or @c character. + pattern match. @c \\0 corresponds to the entire match and @c \& is a + synonym for it. Backslash may be used to quote itself or @c \& character. + @a maxMatches may be used to limit the number of replacements made, setting it to 1, for example, will only replace first occurrence (if any) of the pattern in the text while default value of 0 means replace all. -- 2.47.2