From 4cc4bfafe5a31cb96f35b3ec9b19fa2b0b3a4eef Mon Sep 17 00:00:00 2001 From: Francesco Montorsi Date: Sun, 9 Mar 2008 12:33:59 +0000 Subject: [PATCH] removed @NULL,@true,@false tags from the function prototypes; fixed * and & displacing in the prototypes; changed @param as discussed on wx-dev; use @see instead of @sa; better indentation for @returns,@remarks,@see paragraphs; other misc fixes git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52407 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- interface/aboutdlg.h | 45 +- interface/accel.h | 36 +- interface/access.h | 17 +- interface/animate.h | 112 ++- interface/app.h | 258 +++--- interface/apptrait.h | 20 +- interface/archive.h | 207 +++-- interface/arrstr.h | 55 +- interface/artprov.h | 47 +- interface/atomic.h | 2 +- interface/aui/aui.h | 71 +- interface/aui/auibook.h | 16 +- interface/aui/dockart.h | 20 +- interface/base64.h | 77 +- interface/bitmap.h | 420 ++++++---- interface/bmpbuttn.h | 76 +- interface/bmpcbox.h | 50 +- interface/brush.h | 255 ++++-- interface/buffer.h | 28 +- interface/busyinfo.h | 7 +- interface/button.h | 46 +- interface/calctrl.h | 30 +- interface/caret.h | 18 +- interface/chartype.h | 7 +- interface/checkbox.h | 45 +- interface/checklst.h | 40 +- interface/choicdlg.h | 207 +++-- interface/choice.h | 46 +- interface/clipboard.h | 18 +- interface/clipbrd.h | 18 +- interface/clrpicker.h | 37 +- interface/cmdline.h | 45 +- interface/cmdproc.h | 21 +- interface/cmndata.h | 34 +- interface/collpane.h | 39 +- interface/colordlg.h | 26 +- interface/colour.h | 36 +- interface/combo.h | 140 ++-- interface/combobox.h | 71 +- interface/config.h | 181 ++--- interface/control.h | 6 +- interface/convauto.h | 5 +- interface/cpp.h | 11 +- interface/cshelp.h | 45 +- interface/ctrlsub.h | 164 ++-- interface/cursor.h | 371 ++++++--- interface/dataobj.h | 31 +- interface/dataview.h | 99 +-- interface/datectrl.h | 62 +- interface/datetime.h | 262 +++--- interface/datstrm.h | 79 +- interface/dc.h | 396 ++++----- interface/dcbuffer.h | 53 +- interface/dcmemory.h | 5 +- interface/dcmirror.h | 3 +- interface/dcprint.h | 7 +- interface/dcps.h | 17 +- interface/dcscreen.h | 15 +- interface/dcsvg.h | 116 +-- interface/dde.h | 18 +- interface/debug.h | 65 +- interface/debugrpt.h | 26 +- interface/defs.h | 18 +- interface/dialog.h | 140 ++-- interface/dialup.h | 31 +- interface/dir.h | 37 +- interface/dirctrl.h | 38 +- interface/dirdlg.h | 24 +- interface/display.h | 12 +- interface/dnd.h | 114 ++- interface/docmdi.h | 15 +- interface/docview.h | 250 ++---- interface/dragimag.h | 73 +- interface/dynarray.h | 111 +-- interface/dynlib.h | 98 +-- interface/editlbox.h | 25 +- interface/encconv.h | 17 +- interface/event.h | 430 ++++------ interface/fdrepdlg.h | 12 +- interface/ffile.h | 58 +- interface/file.h | 49 +- interface/fileconf.h | 22 +- interface/filectrl.h | 43 +- interface/filedlg.h | 47 +- interface/filefn.h | 95 +-- interface/filename.h | 209 ++--- interface/filepicker.h | 83 +- interface/filesys.h | 69 +- interface/font.h | 434 ++++++---- interface/fontdlg.h | 11 +- interface/fontenum.h | 15 +- interface/fontmap.h | 21 +- interface/fontpicker.h | 37 +- interface/frame.h | 183 ++--- interface/fs_mem.h | 10 +- interface/gauge.h | 46 +- interface/gbsizer.h | 10 +- interface/gdicmn.h | 117 ++- interface/glcanvas.h | 81 +- interface/graphics.h | 44 +- interface/grid.h | 223 ++--- interface/hash.h | 18 +- interface/help.h | 53 +- interface/html/helpctrl.h | 39 +- interface/html/helpdlg.h | 11 +- interface/html/helpfrm.h | 11 +- interface/html/helpwnd.h | 20 +- interface/html/htmlcell.h | 353 +++++--- interface/html/htmlfilt.h | 2 - interface/html/htmlpars.h | 70 +- interface/html/htmltag.h | 42 +- interface/html/htmlwin.h | 137 ++-- interface/html/htmprint.h | 103 +-- interface/html/winpars.h | 28 +- interface/htmllbox.h | 25 +- interface/hyperlink.h | 56 +- interface/icon.h | 198 +++-- interface/iconloc.h | 2 +- interface/image.h | 788 +++++++++++------- interface/imaglist.h | 114 +-- interface/init.h | 8 +- interface/intl.h | 180 ++--- interface/ipc.h | 21 +- interface/joystick.h | 27 +- interface/layout.h | 43 +- interface/laywin.h | 77 +- interface/link.h | 2 - interface/list.h | 45 +- interface/listbox.h | 86 +- interface/listctrl.h | 233 ++---- interface/log.h | 102 +-- interface/longlong.h | 16 +- interface/math.h | 2 +- interface/mdi.h | 131 ++- interface/mediactrl.h | 80 +- interface/memory.h | 57 +- interface/menu.h | 335 ++++---- interface/menuitem.h | 65 +- interface/metafile.h | 16 +- interface/mimetype.h | 56 +- interface/minifram.h | 34 +- interface/module.h | 13 +- interface/msgdlg.h | 147 ++-- interface/msgqueue.h | 13 +- interface/mstream.h | 19 +- interface/msw/ole/activex.h | 32 +- interface/msw/ole/automtn.h | 71 +- interface/msw/registry.h | 47 +- interface/notebook.h | 144 ++-- interface/notifmsg.h | 7 +- interface/numdlg.h | 14 +- interface/object.h | 118 ++- interface/odcombo.h | 54 +- interface/palette.h | 60 +- interface/panel.h | 47 +- interface/pen.h | 209 +++-- interface/pickerbase.h | 6 +- interface/platform.h | 4 +- interface/platinfo.h | 23 +- interface/print.h | 74 +- interface/printdlg.h | 6 +- interface/process.h | 55 +- interface/progdlg.h | 38 +- interface/propdlg.h | 12 +- interface/protocol/ftp.h | 33 +- interface/protocol/http.h | 19 +- interface/protocol/protocol.h | 19 +- interface/ptr_scpd.h | 29 +- interface/ptr_shrd.h | 6 +- interface/quantize.h | 2 - interface/radiobox.h | 115 ++- interface/radiobut.h | 36 +- interface/recguard.h | 2 - interface/regex.h | 18 +- interface/region.h | 33 +- interface/renderer.h | 53 +- interface/richtext/richtextbuffer.h | 93 +-- interface/richtext/richtextctrl.h | 99 +-- interface/richtext/richtextformatdlg.h | 28 +- interface/richtext/richtexthtml.h | 2 - interface/richtext/richtextprint.h | 6 +- interface/richtext/richtextstyledlg.h | 24 +- interface/richtext/richtextstyles.h | 30 +- interface/richtext/richtextsymboldlg.h | 31 +- interface/richtext/richtextxml.h | 7 +- interface/sashwin.h | 56 +- interface/sckipc.h | 15 +- interface/scopeguard.h | 12 +- interface/scrolbar.h | 65 +- interface/scrolwin.h | 135 ++-- interface/settings.h | 101 +-- interface/sizer.h | 358 ++++---- interface/slider.h | 87 +- interface/snglinst.h | 20 +- interface/socket.h | 341 +++----- interface/sound.h | 23 +- interface/spinbutt.h | 40 +- interface/spinctrl.h | 44 +- interface/splash.h | 7 +- interface/splitter.h | 204 +++-- interface/srchctrl.h | 29 +- interface/sstream.h | 5 +- interface/stackwalk.h | 15 +- interface/statbmp.h | 32 +- interface/statbox.h | 25 +- interface/statline.h | 23 +- interface/stattext.h | 54 +- interface/statusbr.h | 118 +-- interface/stc/stc.h | 15 +- interface/stdpaths.h | 43 +- interface/stockitem.h | 18 +- interface/stopwatch.h | 7 +- interface/strconv.h | 95 +-- interface/stream.h | 98 +-- interface/string.h | 213 ++--- interface/sysopt.h | 16 +- interface/tarstrm.h | 40 +- interface/taskbar.h | 3 +- interface/textctrl.h | 264 +++--- interface/textdlg.h | 31 +- interface/textfile.h | 16 +- interface/tglbtn.h | 37 +- interface/thread.h | 102 +-- interface/timer.h | 19 +- interface/tipdlg.h | 16 +- interface/tipwin.h | 31 +- interface/tokenzr.h | 2 - interface/toolbar.h | 292 +++---- interface/tooltip.h | 2 - interface/toplevel.h | 141 ++-- interface/treebase.h | 2 +- interface/treebook.h | 43 +- interface/treectrl.h | 177 ++-- interface/txtstrm.h | 58 +- interface/uri.h | 51 +- interface/url.h | 33 +- interface/utils.h | 180 ++--- interface/valgen.h | 11 +- interface/validate.h | 3 +- interface/valtext.h | 122 ++- interface/variant.h | 21 +- interface/vector.h | 6 +- interface/vlbox.h | 64 +- interface/vscroll.h | 108 +-- interface/weakref.h | 4 +- interface/wfstream.h | 15 +- interface/window.h | 1035 ++++++++++-------------- interface/windowid.h | 2 +- interface/wizard.h | 99 +-- interface/wrapsizer.h | 3 +- interface/wupdlock.h | 2 +- interface/wxcrt.h | 40 +- interface/xml/xml.h | 38 +- interface/xrc/xmlres.h | 60 +- interface/zipstrm.h | 31 +- interface/zstream.h | 17 +- 256 files changed, 8715 insertions(+), 10536 deletions(-) diff --git a/interface/aboutdlg.h b/interface/aboutdlg.h index 3159a11a30..c6aebf2edc 100644 --- a/interface/aboutdlg.h +++ b/interface/aboutdlg.h @@ -44,52 +44,54 @@ class wxAboutDialogInfo public: /** Default constructor leaves all fields are initially uninitialized, in general - you should call at least SetVersion(), SetCopyright() and SetDescription(). + you should call at least SetVersion(), + SetCopyright() and + SetDescription(). */ wxAboutDialogInfo(); /** Adds an artist name to be shown in the program credits. - @sa SetArtists() + @see SetArtists() */ void AddArtist(const wxString& artist); /** Adds a developer name to be shown in the program credits. - @sa SetDevelopers() + @see SetDevelopers() */ void AddDeveloper(const wxString& developer); /** Adds a documentation writer name to be shown in the program credits. - @sa SetDocWriters() + @see SetDocWriters() */ void AddDocWriter(const wxString& docwriter); /** Adds a translator name to be shown in the program credits. Notice that if no - translator names are specified explicitely, wxAboutBox will try to use the - translation of the string @c translator-credits from the currently used message - catalog -- this can be used to show just the name of the translator of the - program in the current language. + translator names are specified explicitely, wxAboutBox + will try to use the translation of the string @c translator-credits from + the currently used message catalog -- this can be used to show just the name of + the translator of the program in the current language. - @sa SetTranslators() + @see SetTranslators() */ void AddTranslator(const wxString& translator); /** Sets the the list of artists to be shown in the program credits. - @sa AddArtist() + @see AddArtist() */ void SetArtists(const wxArrayString& artists); /** - Set the short string containing the program copyright information. Notice - that any occurrences of @c "(C)" in @e copyright will be replaced by the + Set the short string containing the program copyright information. Notice that + any occurrences of @c "(C)" in @a copyright will be replaced by the copyright symbol (circled C) automatically, which means that you can avoid using this symbol in the program source code which can be problematic, */ @@ -103,14 +105,14 @@ public: /** Set the list of developers of the program. - @sa AddDeveloper() + @see AddDeveloper() */ void SetDevelopers(const wxArrayString& developers); /** Set the list of documentation writers. - @sa AddDocWriter() + @see AddDocWriter() */ void SetDocWriters(const wxArrayString& docwriters); @@ -125,7 +127,6 @@ public: /** Set the long, multiline string containing the text of the program licence. - Only GTK+ version supports showing the licence text in the native about dialog currently so the generic version will be used under all the other platforms if this method is called. To preserve the native look and feel it is advised that @@ -146,21 +147,22 @@ public: void SetName(const wxString& name); /** - Set the list of translators. Please see AddTranslator() for additional + Set the list of translators. Please see + AddTranslator() for additional discussion. */ void SetTranslators(const wxArrayString& translators); /** Set the version of the program. The version is in free format, i.e. not - necessarily in the @c x.y.z form but it shouldn't contain the "version" word. + necessarily in the @c x.y.z form but it shouldn't contain the "version" + word. */ void SetVersion(const wxString& version); /** Set the web site for the program and its description (which defaults to URL itself if empty). - Please notice that only GTK+ version currently supports showing the link in the native about dialog so if this method is called, the generic version will be used under all the other platforms. @@ -180,7 +182,6 @@ public: which is capable of showing all the fields in @e info, the native dialog is used, otherwise the function falls back to the generic wxWidgets version of the dialog, i.e. does the same thing as wxGenericAboutBox. - Here is an example of how this function may be used: @code @@ -208,11 +209,11 @@ void wxAboutBox(const wxAboutDialogInfo& info); native one. This is mainly useful if you need to customize the dialog by e.g. adding custom controls to it (customizing the native dialog is not currently supported). - See the @ref overview_sampledialogs "dialogs sample" for an example of about - dialog customization. + dialog + customization. - @sa wxAboutDialogInfo + @see wxAboutDialogInfo */ void wxGenericAboutBox(const wxAboutDialogInfo& info); diff --git a/interface/accel.h b/interface/accel.h index 167253fc46..e2f5a6c0ea 100644 --- a/interface/accel.h +++ b/interface/accel.h @@ -27,14 +27,13 @@ public: Constructor. @param flags - One of wxACCEL_ALT, wxACCEL_SHIFT, wxACCEL_CTRL and wxACCEL_NORMAL. Indicates - which modifier key is held down. - + One of wxACCEL_ALT, wxACCEL_SHIFT, wxACCEL_CTRL and wxACCEL_NORMAL. + Indicates + which modifier key is held down. @param keyCode - The keycode to be detected. See Keycodes for a full list of keycodes. - + The keycode to be detected. See Keycodes for a full list of keycodes. @param cmd - The menu or control command identifier. + The menu or control command identifier. */ wxAcceleratorEntry(); wxAcceleratorEntry(int flags, int keyCode, int cmd); @@ -59,16 +58,15 @@ public: Sets the accelerator entry parameters. @param flags - One of wxACCEL_ALT, wxACCEL_SHIFT, wxACCEL_CTRL and wxACCEL_NORMAL. Indicates - which modifier key is held down. - + One of wxACCEL_ALT, wxACCEL_SHIFT, wxACCEL_CTRL and wxACCEL_NORMAL. + Indicates + which modifier key is held down. @param keyCode - The keycode to be detected. See Keycodes for a full list of keycodes. - + The keycode to be detected. See Keycodes for a full list of keycodes. @param cmd - The menu or control command identifier. + The menu or control command identifier. */ -#define void Set(int flags, int keyCode, int cmd) /* implementation is private */ + void Set(int flags, int keyCode, int cmd); }; @@ -104,13 +102,11 @@ public: Loads the accelerator table from a Windows resource (Windows only). @param n - Number of accelerator entries. - + Number of accelerator entries. @param entries - The array of entries. - + The array of entries. @param resource - Name of a Windows accelerator. + Name of a Windows accelerator. */ wxAcceleratorTable(); wxAcceleratorTable(const wxAcceleratorTable& bitmap); @@ -128,13 +124,13 @@ public: /** Returns @true if the accelerator table is valid. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** Assignment operator, using @ref overview_trefcount "reference counting". @param accel - Accelerator table to assign. + Accelerator table to assign. */ wxAcceleratorTable operator =(const wxAcceleratorTable& accel); }; diff --git a/interface/access.h b/interface/access.h index 65c0239406..977286b0e2 100644 --- a/interface/access.h +++ b/interface/access.h @@ -50,7 +50,7 @@ public: Constructor, taking an optional window. The object can be associated with a window later. */ - wxAccessible(wxWindow* win = @NULL); + wxAccessible(wxWindow* win = NULL); /** Destructor. @@ -58,7 +58,7 @@ public: ~wxAccessible(); /** - Performs the default action for the object. @e childId is 0 (the action for + Performs the default action for the object. @a childId is 0 (the action for this object) or greater than 0 (the action for a child). Return wxACC_NOT_SUPPORTED if there is no default action for this window (e.g. an edit control). @@ -66,7 +66,7 @@ public: virtual wxAccStatus DoDefaultAction(int childId); /** - Gets the specified child (starting from 1). If @e child is @NULL and the return + Gets the specified child (starting from 1). If @a child is @NULL and the return value is wxACC_OK, this means that the child is a simple element and not an accessible object. */ @@ -79,7 +79,7 @@ public: /** Gets the default action for this object (0) or a child (greater than 0). - Return wxACC_OK even if there is no action. @e actionName is the action, or the + Return wxACC_OK even if there is no action. @a actionName is the action, or the empty string if there is no action. The retrieved string describes the action that is performed on an object, @@ -119,7 +119,7 @@ public: /** Returns the rectangle for this object (id is 0) or a child element (id is greater than 0). - @e rect is in screen coordinates. + @a rect is in screen coordinates. */ virtual wxAccStatus GetLocation(wxRect& rect, int elementId); @@ -142,9 +142,7 @@ public: /** Gets a variant representing the selected children of this object. - Acceptable values are: - a null variant (IsNull() returns TRUE) a list variant (GetType() == wxT("list")) an integer representing the selected child element, @@ -175,14 +173,13 @@ public: this or a child object. Can return either a child object, or an integer representing the child element, starting from 1. - - @e pt is in screen coordinates. + @a pt is in screen coordinates. */ virtual wxAccStatus HitTest(const wxPoint& pt, int* childId, wxAccessible** childObject); /** - Navigates from @e fromId to @e toId/@e toObject. + Navigates from @a fromId to @e toId/@e toObject. */ virtual wxAccStatus Navigate(wxNavDir navDir, int fromId, int* toId, diff --git a/interface/animate.h b/interface/animate.h index 8358478133..24dbe307af 100644 --- a/interface/animate.h +++ b/interface/animate.h @@ -42,7 +42,7 @@ public: Initializes the object and calls Create() with all the parameters. */ - wxAnimationCtrl(wxWindow * parent, wxWindowID id, + wxAnimationCtrl(wxWindow* parent, wxWindowID id, const wxAnimation& anim, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, @@ -56,30 +56,24 @@ public: of the animation is displayed. @param parent - Parent window, must be non-@NULL. - + Parent window, must be non-@NULL. @param id - The identifier for the control. - + The identifier for the control. @param anim - The initial animation shown in the control. - + The initial animation shown in the control. @param pos - Initial position. - + Initial position. @param size - Initial size. - + Initial size. @param style - The window style, see wxAC_* flags. - + The window style, see wxAC_* flags. @param name - Control name. + Control name. @returns @true if the control was successfully created or @false if - creation failed. + creation failed. */ - bool Create(wxWindow * parent, wxWindowID id, + bool Create(wxWindow* parent, wxWindowID id, const wxAnimation& anim, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, @@ -106,7 +100,7 @@ public: Loads the animation from the given file and calls SetAnimation(). See wxAnimation::LoadFile for more info. */ - bool LoadFile(const wxString & file, + bool LoadFile(const wxString& file, wxAnimationType animType = wxANIMATION_TYPE_ANY); /** @@ -122,12 +116,11 @@ public: /** Sets the animation to play in this control. If the previous animation is being played, it's @ref stop() Stopped. - Until Play() isn't called, a static image, the first frame of the given animation or the background colour will be shown (see SetInactiveBitmap() for more info). */ - void SetAnimation(const wxAnimation & anim); + void SetAnimation(const wxAnimation& anim); /** Sets the bitmap to show on the control when it's not playing an animation. @@ -137,12 +130,10 @@ public: if there's no valid animation associated with the control (see wxAnimationCtrl::SetAnimation), then the background colour of the window is shown. - If the control is not playing the animation, the given bitmap will be immediately shown, otherwise it will be shown as soon as Stop() is called. - Note that the inactive bitmap, if smaller than the control's size, will be centered in the control; if bigger, it will be stretched to fit it. @@ -185,10 +176,9 @@ public: Loads an animation from a file. @param name - The name of the file to load. - + The name of the file to load. @param type - See LoadFile for more info. + See LoadFile for more info. */ wxAnimation(); wxAnimation(const wxAnimation& anim); @@ -227,32 +217,50 @@ public: /** Returns @true if animation data is present. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** Loads an animation from the given stream. @param stream - The stream to use to load the animation. - + The stream to use to load the animation. @param type - One of the following values: + One of the following values: + + + + + + + + wxANIMATION_TYPE_GIF + + + + + Load an animated GIF file. + + + - wxANIMATION_TYPE_GIF + wxANIMATION_TYPE_ANI - Load an animated GIF file. - wxANIMATION_TYPE_ANI + Load an ANI file. - Load an ANI file. - wxANIMATION_TYPE_ANY - Try to autodetect the filetype. + + wxANIMATION_TYPE_ANY + + + + + Try to autodetect the filetype. @returns @true if the operation succeeded, @false otherwise. */ @@ -263,26 +271,44 @@ public: Loads an animation from a file. @param name - A filename. - + A filename. @param type - One of the following values: + One of the following values: + + + + + + + + wxANIMATION_TYPE_GIF + + + + + Load an animated GIF file. + + + + + + wxANIMATION_TYPE_ANI + + + + Load an ANI file. - wxANIMATION_TYPE_GIF - Load an animated GIF file. - wxANIMATION_TYPE_ANI + wxANIMATION_TYPE_ANY - Load an ANI file. - wxANIMATION_TYPE_ANY - Try to autodetect the filetype. + Try to autodetect the filetype. @returns @true if the operation succeeded, @false otherwise. */ diff --git a/interface/app.h b/interface/app.h index ac9172f60e..5ed7fe49d8 100644 --- a/interface/app.h +++ b/interface/app.h @@ -51,7 +51,7 @@ public: Creates a wxLog class for the application to use for logging errors. The default implementation returns a new wxLogGui class. - @sa wxLog + @see wxLog */ virtual wxLog* CreateLogTarget(); @@ -59,16 +59,15 @@ public: Creates the wxAppTraits object when GetTraits() needs it for the first time. - @sa wxAppTraits + @see wxAppTraits */ - virtual wxAppTraits * CreateTraits(); + virtual wxAppTraits* CreateTraits(); /** Dispatches the next event in the windowing system event queue. - This can be used for programming event loops, e.g. - @sa Pending() + @see Pending() */ virtual void Dispatch(); @@ -95,9 +94,7 @@ public: is meant to be shown to the user and so should be used for the window titles, page headers and so on while the other one should be only used internally, e.g. for the file names or configuration file keys. - By default, returns the same string as GetAppName(). - This function is new since wxWidgets version 2.9.0 */ wxString GetAppDisplayName(); @@ -106,10 +103,9 @@ public: Returns the application name. @remarks wxWidgets sets this to a reasonable default before calling - OnInit(), but the application can reset it at - will. + OnInit(), but the application can reset it at will. - @sa GetAppDisplayName() + @see GetAppDisplayName() */ wxString GetAppName(); @@ -118,7 +114,7 @@ public: platform specific manner to refer to the application. - @sa SetClassName() + @see SetClassName() */ wxString GetClassName(); @@ -127,8 +123,8 @@ public: @false otherwise. - @sa SetExitOnFrameDelete(), @ref overview_wxappshutdownoverview "wxApp - shutdown overview" + @see SetExitOnFrameDelete(), @ref overview_wxappshutdownoverview "wxApp + shutdown overview" */ bool GetExitOnFrameDelete(); @@ -136,33 +132,33 @@ public: Returns the one and only global application object. Usually @c wxTheApp is usead instead. - @sa SetInstance() + @see SetInstance() */ - static wxAppConsole * GetInstance(); + static wxAppConsole* GetInstance(); /** Returns a pointer to the top window. @remarks If the top window hasn't been set using SetTopWindow(), - this function will find the first top-level window - (frame or dialog) and return that. + this function will find the first top-level window + (frame or dialog) and return that. - @sa SetTopWindow() + @see SetTopWindow() */ - virtual wxWindow * GetTopWindow(); + virtual wxWindow* GetTopWindow(); /** Returns a pointer to the wxAppTraits object for the application. If you want to customize the wxAppTraits object, you must override the CreateTraits() function. */ - wxAppTraits * GetTraits(); + wxAppTraits* GetTraits(); /** Returns @true if the application will use the best visual on systems that support different visuals, @false otherwise. - @sa SetUseBestVisual() + @see SetUseBestVisual() */ bool GetUseBestVisual(); @@ -172,9 +168,7 @@ public: is meant to be shown to the user and so should be used for the window titles, page headers and so on while the other one should be only used internally, e.g. for the file names or configuration file keys. - By default, returns the same string as GetVendorName(). - This function is new since wxWidgets version 2.9.0 */ wxString GetVendorDisplayName(); @@ -185,8 +179,8 @@ public: wxString GetVendorName(); /** - This function simply invokes the given method @e func of the specified - event handler @e handler with the @e event as parameter. It exists solely + This function simply invokes the given method @a func of the specified + event handler @a handler with the @a event as parameter. It exists solely to allow to catch the C++ exceptions which could be thrown by all event handlers in the application in one place: if you want to do this, override this function in your wxApp-derived class and add try/catch clause(s) to it. @@ -207,7 +201,6 @@ public: /** Returns @true if the main event loop is currently running, i.e. if the application is inside OnRun(). - This can be useful to test whether events can be dispatched. For example, if this function returns @false, non-blocking sockets cannot be used because the events from them would never be processed. @@ -249,7 +242,7 @@ public: to provide your own (environment-dependent) main loop. @returns Returns 0 under X, and the wParam of the WM_QUIT message under - Windows. + Windows. */ virtual int MainLoop(); @@ -258,28 +251,23 @@ public: specified in wxASSERT macro evaluated to @false. It is only called in debug mode (when @c __WXDEBUG__ is defined) as asserts are not left in the release code at all. - The base class version shows the default assert failure dialog box proposing to the user to stop the program, continue or ignore all subsequent asserts. @param file - the name of the source file where the assert occurred - + the name of the source file where the assert occurred @param line - the line number in this file where the assert occurred - + the line number in this file where the assert occurred @param func - the name of the function where the assert occurred, may be - empty if the compiler doesn't support C99 __FUNCTION__ - + the name of the function where the assert occurred, may be + empty if the compiler doesn't support C99 __FUNCTION__ @param cond - the condition of the failed assert in text form - + the condition of the failed assert in text form @param msg - the message specified as argument to - wxASSERT_MSG or wxFAIL_MSG, will - be @NULL if just wxASSERT or wxFAIL - was used + the message specified as argument to + wxASSERT_MSG or wxFAIL_MSG, will + be @NULL if just wxASSERT or wxFAIL + was used */ void OnAssertFailure(const wxChar file, int line, const wxChar func, @@ -290,22 +278,20 @@ public: Called when command line parsing fails (i.e. an incorrect command line option was specified by the user). The default behaviour is to show the program usage text and abort the program. - Return @true to continue normal execution or @false to return @false from OnInit() thus terminating the program. - @sa OnInitCmdLine() + @see OnInitCmdLine() */ bool OnCmdLineError(wxCmdLineParser& parser); /** Called when the help option (@c --help) was specified on the command line. The default behaviour is to show the program usage text and abort the program. - Return @true to continue normal execution or @false to return @false from OnInit() thus terminating the program. - @sa OnInitCmdLine() + @see OnInitCmdLine() */ bool OnCmdLineHelp(wxCmdLineParser& parser); @@ -313,14 +299,12 @@ public: Called after the command line had been successfully parsed. You may override this method to test for the values of the various parameters which could be set from the command line. - Don't forget to call the base class version unless you want to suppress processing of the standard command line options. - Return @true to continue normal execution or @false to return @false from OnInit() thus terminating the program. - @sa OnInitCmdLine() + @see OnInitCmdLine() */ bool OnCmdLineParsed(wxCmdLineParser& parser); @@ -330,12 +314,10 @@ public: continue running the loop or @false to exit the loop and terminate the program. In the latter case it can also use C++ @c throw keyword to rethrow the current exception. - The default behaviour of this function is the latter in all ports except under Windows where a dialog is shown to the user which allows him to choose between the different options. You may override this function in your class to do something more appropriate. - Finally note that if the exception is rethrown from here, it can be caught in OnUnhandledException(). */ @@ -347,7 +329,6 @@ public: destroying all application windows and controls, but before wxWidgets cleanup. Note that it is not called at all if OnInit() failed. - The return value of this function is currently ignored, return the same value as returned by the base class method if you override it. */ @@ -358,12 +339,11 @@ public: exception under Win32 or a a fatal signal under Unix, for example. However, this will not happen by default: you have to explicitly call wxHandleFatalExceptions to enable this. - Generally speaking, this function should only show a message to the user and return. You may attempt to save unsaved data but this is not guaranteed to work and, in fact, probably won't. - @sa wxHandleFatalExceptions + @see wxHandleFatalExceptions */ void OnFatalException(); @@ -373,11 +353,9 @@ public: SetTopWindow(). You may use OnExit() to clean up anything initialized here, provided that the function returns @true. - Notice that if you want to to use the command line processing provided by wxWidgets you have to call the base class version in the derived class OnInit(). - Return @true to continue processing, @false to exit the application immediately. */ @@ -398,7 +376,6 @@ public: the last frame has been deleted and GetExitOnFrameDelete() flag is @true (this is the default). - The return value of this function becomes the exit code of the program, so it should return 0 in case of successful termination. */ @@ -411,7 +388,6 @@ public: event loop has been terminated and the program will exit, if you want to prevent this from happening (i.e. continue running after catching an exception) you need to override OnExceptionInMainLoop(). - The default implementation shows information about the exception in debug build but does nothing in the release build. */ @@ -420,7 +396,7 @@ public: /** Returns @true if unprocessed events are in the window system event queue. - @sa Dispatch() + @see Dispatch() */ virtual bool Pending(); @@ -434,19 +410,18 @@ public: to allow co-existence with the Microsoft Foundation Classes, override the PreTranslateMessage function: */ - bool ProcessMessage(WXMSG * msg); + bool ProcessMessage(WXMSG* msg); /** Sends idle events to a window and its children. - Please note that this function is internal to wxWidgets and shouldn't be used by user code. @remarks These functions poll the top-level windows, and their children, - for idle event processing. If @true is returned, more - OnIdle processing is requested by one or more window. + for idle event processing. If @true is returned, more + OnIdle processing is requested by one or more window. - @sa wxIdleEvent + @see wxIdleEvent */ bool SendIdleEvents(wxWindow* win, wxIdleEvent& event); @@ -462,10 +437,9 @@ public: configuration file entries and other internal strings. For the user-visible strings, such as the window titles, the application display name set by SetAppDisplayName() is used instead. - By default the application name is set to the name of its executable file. - @sa GetAppName() + @see GetAppName() */ void SetAppName(const wxString& name); @@ -473,7 +447,7 @@ public: Sets the class name of the application. This may be used in a platform specific manner to refer to the application. - @sa GetClassName() + @see GetClassName() */ void SetClassName(const wxString& name); @@ -482,11 +456,11 @@ public: top-level frame is deleted. @param flag - If @true (the default), the application will exit when the top-level frame is - deleted. If @false, the application will continue to run. + If @true (the default), the application will exit when the top-level frame is + deleted. If @false, the application will continue to run. - @sa GetExitOnFrameDelete(), @ref overview_wxappshutdownoverview "wxApp - shutdown overview" + @see GetExitOnFrameDelete(), @ref overview_wxappshutdownoverview "wxApp + shutdown overview" */ void SetExitOnFrameDelete(bool flag); @@ -495,20 +469,19 @@ public: know what you're doing if you call it. @param app - Replacement for the global application object. + Replacement for the global application object. - @sa GetInstance() + @see GetInstance() */ static void SetInstance(wxAppConsole* app); /** Allows runtime switching of the UI environment theme. Currently implemented for wxGTK2-only. - Return @true if theme was successfully changed. @param theme - The name of the new theme or an absolute path to a gtkrc-theme-file + The name of the new theme or an absolute path to a gtkrc-theme-file */ bool SetNativeTheme(); @@ -525,9 +498,9 @@ public: needs to use the top window. @param window - The new top window. + The new top window. - @sa GetTopWindow(), OnInit() + @see GetTopWindow(), OnInit() */ void SetTopWindow(wxWindow* window); @@ -539,19 +512,16 @@ public: case under Solaris and IRIX, where the default visual is only 8-bit whereas certain applications are supposed to run in TrueColour mode. - - If @e forceTrueColour is @true then the application will try to force + If @a forceTrueColour is @true then the application will try to force using a TrueColour visual and abort the app if none is found. - Note that this function has to be called in the constructor of the @c wxApp instance and won't have any effect when called later on. - This function currently only has effect under GTK. @param flag - If @true, the app will use the best visual. + If @true, the app will use the best visual. */ - void SetUseBestVisual(bool flag, bool forceTrueColour = @false); + void SetUseBestVisual(bool flag, bool forceTrueColour = false); /** Set the vendor name to be used in the user-visible places. See @@ -565,7 +535,7 @@ public: in registry access. A default name is set by wxWidgets. - @sa GetVendorName() + @see GetVendorName() */ void SetVendorName(const wxString& name); @@ -575,42 +545,36 @@ public: time-consuming process writes to a text window. Without an occasional yield, the text window will not be updated properly, and on systems with cooperative multitasking, such as Windows 3.1 other processes will not respond. - Caution should be exercised, however, since yielding may allow the user to perform actions which are not compatible with the current task. Disabling menu items or whole menus during processing can avoid unwanted reentrance of code: see ::wxSafeYield for a better function. - Note that Yield() will not flush the message logs. This is intentional as calling Yield() is usually done to quickly update the screen and popping up a message box dialog may be undesirable. If you do wish to flush the log messages immediately (otherwise it will be done during the next idle loop iteration), call wxLog::FlushActive. - Calling Yield() recursively is normally an error and an assert failure is raised in debug build if such situation is detected. However if the - @e onlyIfNeeded parameter is @true, the method will just silently + @a onlyIfNeeded parameter is @true, the method will just silently return @false instead. */ - bool Yield(bool onlyIfNeeded = @false); + bool Yield(bool onlyIfNeeded = false); /** int argc - Number of command line arguments (after environment-specific processing). */ /** wxChar ** argv - Command line arguments (after environment-specific processing). Under Windows and Linux/Unix, you should parse the command line arguments and check for files to be opened when starting your application. Under OS X, you need to override MacOpenFile() since command line arguments are used differently there. - You may use the wxCmdLineParser to parse command line arguments. */ @@ -626,8 +590,8 @@ public: For all normal, informational messages. They also appear in a message box by default (but it can be changed). */ -void wxLogMessage(const char * formatString, ... ); -void wxVLogMessage(const char * formatString, va_list argPtr); +void wxLogMessage(const char* formatString, ... ); +void wxVLogMessage(const char* formatString, va_list argPtr); //@} //@{ @@ -637,8 +601,8 @@ void wxVLogMessage(const char * formatString, va_list argPtr); progress (another, but possibly confusing name for the same function is @b wxLogInfo). */ -void wxLogVerbose(const char * formatString, ... ); -void wxVLogVerbose(const char * formatString, va_list argPtr); +void wxLogVerbose(const char* formatString, ... ); +void wxVLogVerbose(const char* formatString, va_list argPtr); //@} /** @@ -646,8 +610,8 @@ void wxVLogVerbose(const char * formatString, va_list argPtr); wxGetApp function implemented by wxIMPLEMENT_APP. It creates the declaration @c className wxGetApp(void). - Example: + @code wxDECLARE_APP(MyApp) @endcode @@ -667,8 +631,8 @@ void wxExit(); For warnings - they are also normally shown to the user, but don't interrupt the program work. */ -void wxLogWarning(const char * formatString, ... ); -void wxVLogWarning(const char * formatString, va_list argPtr); +void wxLogWarning(const char* formatString, ... ); +void wxVLogWarning(const char* formatString, va_list argPtr); //@} //@{ @@ -677,38 +641,38 @@ void wxVLogWarning(const char * formatString, va_list argPtr); terminates the program with the exit code 3. Using @e abort() standard function also terminates the program with this exit code. */ -void wxLogFatalError(const char * formatString, ... ); -void wxVLogFatalError(const char * formatString, +void wxLogFatalError(const char* formatString, ... ); +void wxVLogFatalError(const char* formatString, va_list argPtr); //@} /** - If @e doIt is @true, the fatal exceptions (also known as general protection + If @a doIt is @true, the fatal exceptions (also known as general protection faults under Windows or segmentation violations in the Unix world) will be caught and passed to wxApp::OnFatalException. By default, i.e. before this function is called, they will be handled in the normal way which usually just means that the application will be terminated. - Calling wxHandleFatalExceptions() with @e doIt equal to @false will restore + Calling wxHandleFatalExceptions() with @a doIt equal to @false will restore this default behaviour. - Notice that this function is only available if @c wxUSE_ON_FATAL_EXCEPTION is 1 and under Windows platform this requires a compiler with support for SEH (structured exception handling) which currently means only Microsoft Visual C++ or a recent Borland C++ version. */ -bool wxHandleFatalExceptions(bool doIt = @true); +bool wxHandleFatalExceptions(bool doIt = true); /** This is used in the application class implementation file to make the application class known to wxWidgets for dynamic construction. You use this instead of - Old form: + @code MyApp myApp; @endcode New form: + @code IMPLEMENT_APP(MyApp) @endcode @@ -721,18 +685,18 @@ bool wxHandleFatalExceptions(bool doIt = @true); Returns the error code from the last system call. This function uses @c errno on Unix platforms and @c GetLastError under Win32. - @sa wxSysErrorMsg, wxLogSysError + @see wxSysErrorMsg, wxLogSysError */ unsigned long wxSysErrorCode(); /** - In a GUI application, this function posts @e event to the specified @e dest + In a GUI application, this function posts @a event to the specified @e dest object using wxEvtHandler::AddPendingEvent. - Otherwise, it dispatches @e event immediately using + Otherwise, it dispatches @a event immediately using wxEvtHandler::ProcessEvent. See the respective documentation for details (and caveats). */ -void wxPostEvent(wxEvtHandler * dest, wxEvent& event); +void wxPostEvent(wxEvtHandler* dest, wxEvent& event); //@{ /** @@ -740,8 +704,8 @@ void wxPostEvent(wxEvtHandler * dest, wxEvent& event); to the user. The default processing is to pop up a message box to inform the user about it. */ -void wxLogError(const char * formatString, ... ); -void wxVLogError(const char * formatString, va_list argPtr); +void wxLogError(const char* formatString, ... ); +void wxVLogError(const char* formatString, va_list argPtr); //@} //@{ @@ -750,26 +714,22 @@ void wxVLogError(const char * formatString, va_list argPtr); expand to nothing in the release one. The reason for making it a separate function from it is that usually there are a lot of trace messages, so it might make sense to separate them from other debug messages. - The trace messages also usually can be separated into different categories and the second and third versions of this function only log the message if the - @e mask which it has is currently enabled in wxLog. This + @a mask which it has is currently enabled in wxLog. This allows to selectively trace only some operations and not others by changing the value of the trace mask (possible during the run-time). - For the second function (taking a string mask), the message is logged only if the mask has been previously enabled by the call to wxLog::AddTraceMask or by setting @ref overview_envvars "@c WXTRACE environment variable". The predefined string trace masks used by wxWidgets are: - wxTRACE_MemAlloc: trace memory allocation (new/delete) wxTRACE_Messages: trace window messages/X callbacks wxTRACE_ResAlloc: trace GDI resource allocation wxTRACE_RefCount: trace various ref counting operations wxTRACE_OleCalls: trace OLE method calls (Win32 only) - @b Caveats: since both the mask and the format string are strings, this might lead to function signature confusion in some cases: if you intend to call the format string only version of wxLogTrace, @@ -777,41 +737,39 @@ void wxVLogError(const char * formatString, va_list argPtr); for that %s, the string mask version of wxLogTrace will erroneously get called instead, since you are supplying two string parameters to the function. In this case you'll unfortunately have to avoid having two leading string parameters, e.g. by adding a bogus integer (with its %d format string). - The third version of the function only logs the message if all the bits - corresponding to the @e mask are set in the wxLog trace mask which can be + corresponding to the @a mask are set in the wxLog trace mask which can be set by wxLog::SetTraceMask. This version is less flexible than the previous one because it doesn't allow defining the user trace masks easily - this is why it is deprecated in favour of using string trace masks. - wxTraceMemAlloc: trace memory allocation (new/delete) wxTraceMessages: trace window messages/X callbacks wxTraceResAlloc: trace GDI resource allocation wxTraceRefCount: trace various ref counting operations wxTraceOleCalls: trace OLE method calls (Win32 only) */ -void wxLogTrace(const char * formatString, ... ); -void wxVLogTrace(const char * formatString, va_list argPtr); -void wxLogTrace(const char * mask, const char * formatString, +void wxLogTrace(const char* formatString, ... ); +void wxVLogTrace(const char* formatString, va_list argPtr); +void wxLogTrace(const char* mask, const char* formatString, ... ); -void wxVLogTrace(const char * mask, - const char * formatString, +void wxVLogTrace(const char* mask, + const char* formatString, va_list argPtr); -void wxLogTrace(wxTraceMask mask, const char * formatString, +void wxLogTrace(wxTraceMask mask, const char* formatString, ... ); -void wxVLogTrace(wxTraceMask mask, const char * formatString, +void wxVLogTrace(wxTraceMask mask, const char* formatString, va_list argPtr); //@} /** Returns the error message corresponding to the given system error code. If - @e errCode is 0 (default), the last error code (as returned by + @a errCode is 0 (default), the last error code (as returned by wxSysErrorCode) is used. - @sa wxSysErrorCode, wxLogSysError + @see wxSysErrorCode, wxLogSysError */ -const wxChar * wxSysErrorMsg(unsigned long errCode = 0); +const wxChar* wxSysErrorMsg(unsigned long errCode = 0); /** This function is for use in console (wxBase) programs only. It must be called @@ -825,8 +783,8 @@ void wxUninitialize(); mode (when the preprocessor symbol __WXDEBUG__ is defined) and expand to nothing in release mode (otherwise). */ -void wxLogDebug(const char * formatString, ... ); -void wxVLogDebug(const char * formatString, va_list argPtr); +void wxLogDebug(const char* formatString, ... ); +void wxVLogDebug(const char* formatString, va_list argPtr); //@} /** @@ -834,7 +792,6 @@ void wxVLogDebug(const char * formatString, va_list argPtr); the IMPLEMENT_APP macro. Thus, before using it anywhere but in the same module where this macro is used, you must make it available using DECLARE_APP. - The advantage of using this function compared to directly using the global wxTheApp pointer is that the latter is of type @c wxApp * and so wouldn't allow you to access the functions specific to your application class but not @@ -844,29 +801,26 @@ wxAppDerivedClass wxGetApp(); //@{ /** - Messages logged by these functions will appear in the statusbar of the @e frame + Messages logged by these functions will appear in the statusbar of the @a frame or of the top level application window by default (i.e. when using the second version of the functions). - If the target frame doesn't have a statusbar, the message will be lost. */ -void wxLogStatus(wxFrame * frame, const char * formatString, +void wxLogStatus(wxFrame* frame, const char* formatString, ... ); -void wxVLogStatus(wxFrame * frame, const char * formatString, +void wxVLogStatus(wxFrame* frame, const char* formatString, va_list argPtr); -void wxLogStatus(const char * formatString, ... ); -void wxVLogStatus(const char * formatString, va_list argPtr); +void wxLogStatus(const char* formatString, ... ); +void wxVLogStatus(const char* formatString, va_list argPtr); //@} /** This function is used in wxBase only and only if you don't create wxApp object at all. In this case you must call it from your @c main() function before calling any other wxWidgets functions. - If the function returns @false the initialization could not be performed, in this case the library cannot be used and wxUninitialize shouldn't be called neither. - This function may be called several times but wxUninitialize must be called for each successful call to this function. @@ -878,8 +832,8 @@ bool wxInitialize(); wxGetApp function implemented by IMPLEMENT_APP. It creates the declaration @c className wxGetApp(void). - Example: + @code DECLARE_APP(MyApp) @endcode @@ -888,7 +842,6 @@ bool wxInitialize(); /** Calls wxApp::Yield. - This function is kept only for backwards compatibility. Please use the wxApp::Yield method instead in any new code. */ @@ -902,10 +855,10 @@ bool wxYield(); on the platform) and the corresponding error message. The second form of this function takes the error code explicitly as the first argument. - @sa wxSysErrorCode, wxSysErrorMsg + @see wxSysErrorCode, wxSysErrorMsg */ -void wxLogSysError(const char * formatString, ... ); -void wxVLogSysError(const char * formatString, +void wxLogSysError(const char* formatString, ... ); +void wxVLogSysError(const char* formatString, va_list argPtr); //@} @@ -915,23 +868,22 @@ void wxVLogSysError(const char * formatString, using the default wxWidgets entry code (e.g. main or WinMain). For example, you can initialize wxWidgets from an Microsoft Foundation Classes application using this function. - The following overload of wxEntry is available under all platforms: (notice that under Windows CE platform, and only there, the type of - @e pCmdLine is @c wchar_t *, otherwise it is @c char *, even in + @a pCmdLine is @c wchar_t *, otherwise it is @c char *, even in Unicode build). @remarks To clean up wxWidgets, call wxApp::OnExit followed by the static - function wxApp::CleanUp. For example, if exiting from - an MFC application that also uses wxWidgets: + function wxApp::CleanUp. For example, if exiting from + an MFC application that also uses wxWidgets: - @sa wxEntryStart + @see wxEntryStart */ -int wxEntry(int& argc, wxChar ** argv); +int wxEntry(int& argc, wxChar** argv); int wxEntry(HINSTANCE hInstance, - HINSTANCE hPrevInstance = @NULL, - char * pCmdLine = @NULL, + HINSTANCE hPrevInstance = NULL, + char* pCmdLine = NULL, int nCmdShow = SW_SHOWNORMAL); //@} diff --git a/interface/apptrait.h b/interface/apptrait.h index f124e737bf..8abc2f94d3 100644 --- a/interface/apptrait.h +++ b/interface/apptrait.h @@ -40,32 +40,31 @@ public: wxApp::GetVendorName methods are used to determine the registry key or file name. */ - virtual wxConfigBase * CreateConfig(); + virtual wxConfigBase* CreateConfig(); /** Creates the global font mapper object used for encodings/charset mapping. */ - virtual wxFontMapper * CreateFontMapper(); + virtual wxFontMapper* CreateFontMapper(); /** Creates the default log target for the application. */ - virtual wxLog * CreateLogTarget(); + virtual wxLog* CreateLogTarget(); /** Creates the global object used for printing out messages. */ - virtual wxMessageOutput * CreateMessageOutput(); + virtual wxMessageOutput* CreateMessageOutput(); /** Returns the renderer to use for drawing the generic controls (return value may be @NULL in which case the default renderer for the current platform is used); this is used in GUI mode only and always returns @NULL in console. - NOTE: returned pointer will be deleted by the caller. */ - virtual wxRendererNative * CreateRenderer(); + virtual wxRendererNative* CreateRenderer(); /** This method returns the name of the desktop environment currently @@ -89,15 +88,13 @@ public: of the native toolkit currently used. The version numbers returned are thus detected at run-time and not compile-time (except when this is not possible e.g. wxMotif). - E.g. if your program is using wxGTK port this function will return wxPORT_GTK and put in given pointers the versions of the GTK library in use. - See wxPlatformInfo for more details. */ - virtual wxPortId GetToolkitVersion(int * major = @NULL, - int * minor = @NULL); + virtual wxPortId GetToolkitVersion(int* major = NULL, + int* minor = NULL); /** Returns @true if @c fprintf(stderr) goes somewhere, @false otherwise. @@ -113,8 +110,7 @@ public: /** Shows the assert dialog with the specified message in GUI mode or just prints the string to stderr in console mode. - Returns @true to suppress subsequent asserts, @false to continue as before. */ - virtual bool ShowAssertDialog(const wxString & msg); + virtual bool ShowAssertDialog(const wxString& msg); }; diff --git a/interface/archive.h b/interface/archive.h index 0ea3de6e03..89efa467ff 100644 --- a/interface/archive.h +++ b/interface/archive.h @@ -47,8 +47,7 @@ public: /** Closes the current entry if one is open, then opens the entry specified by the wxArchiveEntry object. - - @e entry must be from the same archive file that this + @a entry must be from the same archive file that this wxArchiveInputStream is reading, and it must be reading it from a seekable stream. */ @@ -103,13 +102,11 @@ public: as a whole. For example in the case of zip there is a comment, which is stored at the end of the zip file. CopyArchiveMetaData() can be used to transfer such information when writing a modified copy of an archive. - Since the position of the meta-data can vary between the various archive formats, it is best to call CopyArchiveMetaData() before transferring the entries. The wxArchiveOutputStream will then hold on to the meta-data and write it at the correct point in the output file. - When the input archive is being read from a non-seekable stream, the meta-data may not be available when CopyArchiveMetaData() is called, in which case the two streams set up a link and transfer the data @@ -118,16 +115,14 @@ public: bool CopyArchiveMetaData(wxArchiveInputStream& stream); /** - Takes ownership of @e entry and uses it to create a new entry in the - archive. @e entry is then opened in the input stream @e stream + Takes ownership of @a entry and uses it to create a new entry in the + archive. @a entry is then opened in the input stream @e stream and its contents copied to this stream. - For archive types which compress entry data, CopyEntry() is likely to be much more efficient than transferring the data using Read() and Write() since it will copy them without decompressing and recompressing them. - - @e entry must be from the same archive file that @e stream is - accessing. For non-seekable streams, @e entry must also be the last + @a entry must be from the same archive file that @a stream is + accessing. For non-seekable streams, @a entry must also be the last thing read from @e stream. */ bool CopyEntry(wxArchiveEntry* entry, @@ -135,11 +130,9 @@ public: /** ) - Create a new directory entry (see wxArchiveEntry::IsDir) with the given name and timestamp. - PutNextEntry() can also be used to create directory entries, by supplying a name with a trailing path separator. @@ -149,7 +142,6 @@ public: //@{ /** , @b off_t@e size = wxInvalidOffset) - Create a new entry with the given name, timestamp and size. The entry's data can then be written by writing to this wxArchiveOutputStream. */ @@ -195,10 +187,8 @@ public: /** The entry's name, by default in the native format. The name can include directory components, i.e. it can be a full path. - If this is a directory entry, (i.e. if IsDir() is @true) then GetName() returns the name with a trailing path separator. - Similarly, setting a name with a trailing path separator sets IsDir(). */ wxString GetName(wxPathFormat format = wxPATH_NATIVE); @@ -224,11 +214,10 @@ public: Returns the entry's filename in the internal format used within the archive. The name can include directory components, i.e. it can be a full path. - The names of directory entries are returned without any trailing path separator. This gives a canonical name that can be used in comparisons. - @sa @ref overview_wxarcbyname "Looking up an archive entry by name" + @see @ref overview_wxarcbyname "Looking up an archive entry by name" */ wxString GetInternalName(); @@ -240,17 +229,15 @@ public: //@{ /** True if this is a directory entry. - Directory entries are entries with no data, which are used to store the meta-data of directories. They also make it possible for completely empty directories to be stored. - The names of entries within an archive can be complete paths, and unarchivers typically create whatever directories are necessary as they restore files, even if the archive contains no explicit directory entries. */ bool IsDir(); - void SetIsDir(bool isDir = @true); + void SetIsDir(bool isDir = true); //@} //@{ @@ -258,7 +245,7 @@ public: True if the entry is a read-only file. */ bool IsReadOnly(); - void SetIsReadOnly(bool isReadOnly = @true); + void SetIsReadOnly(bool isReadOnly = true); //@} //@{ @@ -268,7 +255,6 @@ public: this entry, it will then invoke the associated notifier's wxArchiveNotifier::OnEntryUpdated method. - Setting a notifier is not usually necessary. It is used to handle certain cases when modifying an archive in a pipeline (i.e. between non-seekable streams). @@ -313,7 +299,6 @@ public: /** Returns @true if this factory can handle the given protocol, MIME type or file extension. - When using wxSTREAM_FILEEXT for the second parameter, the first parameter can be a complete filename rather than just an extension. */ @@ -324,7 +309,6 @@ public: A static member that finds a factory that can handle a given protocol, MIME type or file extension. Returns a pointer to the class factory if found, or @NULL otherwise. It does not give away ownership of the factory. - When using wxSTREAM_FILEEXT for the second parameter, the first parameter can be a complete filename rather than just an extension. */ @@ -344,8 +328,8 @@ public: //@{ /** GetFirst and GetNext can be used to enumerate the available factories. - For example, to list them: + GetFirst()/GetNext() return a pointer to a factory or @NULL if no more are available. They do not give away ownership of the factory. */ @@ -371,10 +355,9 @@ public: Returns the protocols, MIME types or file extensions supported by this factory, as an array of null terminated strings. It does not give away ownership of the array or strings. - For example, to list the file extensions a factory supports: */ - const wxChar * const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL); + const wxChar* const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL); /** Create a new wxArchiveEntry object of the @@ -385,7 +368,6 @@ public: //@{ /** Create a new input or output stream to read or write an archive. - If the parent stream is passed as a pointer then the new archive stream takes ownership of it. If it is passed by reference then it does not. */ @@ -398,15 +380,12 @@ public: /** Adds this class factory to the list returned by @ref getfirst() GetFirst()/GetNext. - It is not necessary to do this to use the archive streams. It is usually used when implementing streams, typically the implementation will add a static instance of its factory class. - It can also be used to change the order of a factory already in the list, bringing it to the front. This isn't a thread safe operation so can't be done when other threads are running that will be using the list. - The list does not take ownership of the factory. */ void PushFront(); @@ -414,10 +393,8 @@ public: /** Removes this class factory from the list returned by @ref getfirst() GetFirst()/GetNext. - Removing from the list isn't a thread safe operation so can't be done when other threads are running that will be using the list. - The list does not own the factories, so removing a factory does not delete it. */ void Remove(); @@ -478,112 +455,112 @@ public: // template parameter 'Arc' should be the type of an archive input stream wxArchiveIterator(Arc& arc) { + // ... + } + }; + @endcode - /* ... */ -}; -@endcode - -The first template parameter should be the type of archive input stream -(e.g. wxArchiveInputStream) and the -second can either be a pointer to an entry -(e.g. wxArchiveEntry*), or a string/pointer pair -(e.g. std::pairwxString, wxArchiveEntry*). + The first template parameter should be the type of archive input stream + (e.g. wxArchiveInputStream) and the + second can either be a pointer to an entry + (e.g. wxArchiveEntry*), or a string/pointer pair + (e.g. std::pairwxString, wxArchiveEntry*). -The @c wx/archive.h header defines the following typedefs: + The @c wx/archive.h header defines the following typedefs: -@code -typedef wxArchiveIteratorwxArchiveInputStream wxArchiveIter; + @code + typedef wxArchiveIteratorwxArchiveInputStream wxArchiveIter; -typedef wxArchiveIteratorwxArchiveInputStream, -std::pairwxString, wxArchiveEntry* wxArchivePairIter; -@endcode + typedef wxArchiveIteratorwxArchiveInputStream, + std::pairwxString, wxArchiveEntry* wxArchivePairIter; + @endcode -The header for any implementation of this interface should define similar -typedefs for its types, for example in @c wx/zipstrm.h there is: + The header for any implementation of this interface should define similar + typedefs for its types, for example in @c wx/zipstrm.h there is: - @code - typedef wxArchiveIteratorwxZipInputStream wxZipIter; + @code + typedef wxArchiveIteratorwxZipInputStream wxZipIter; -typedef wxArchiveIteratorwxZipInputStream, -std::pairwxString, wxZipEntry* wxZipPairIter; -@endcode + typedef wxArchiveIteratorwxZipInputStream, + std::pairwxString, wxZipEntry* wxZipPairIter; + @endcode -Transferring the catalogue of an archive @e arc to a vector @e cat, -can then be done something like this: + Transferring the catalogue of an archive @e arc to a vector @e cat, + can then be done something like this: -@code -std::vectorwxArchiveEntry* cat((wxArchiveIter)arc, wxArchiveIter()); -@endcode + @code + std::vectorwxArchiveEntry* cat((wxArchiveIter)arc, wxArchiveIter()); + @endcode -When the iterator is dereferenced, it gives away ownership of an entry -object. So in the above example, when you have finished with @e cat -you must delete the pointers it contains. + When the iterator is dereferenced, it gives away ownership of an entry + object. So in the above example, when you have finished with @e cat + you must delete the pointers it contains. -If you have smart pointers with normal copy semantics (i.e. not auto_ptr - or wxScopedPtr), then you can create an iterator -which uses them instead. For example, with a smart pointer class for -zip entries @e ZipEntryPtr: + If you have smart pointers with normal copy semantics (i.e. not auto_ptr + or wxScopedPtr), then you can create an iterator + which uses them instead. For example, with a smart pointer class for + zip entries @e ZipEntryPtr: -@code -typedef std::vectorZipEntryPtr ZipCatalog; -typedef wxArchiveIteratorwxZipInputStream, ZipEntryPtr ZipIter; -ZipCatalog cat((ZipIter)zip, ZipIter()); -@endcode + @code + typedef std::vectorZipEntryPtr ZipCatalog; + typedef wxArchiveIteratorwxZipInputStream, ZipEntryPtr ZipIter; + ZipCatalog cat((ZipIter)zip, ZipIter()); + @endcode -Iterators that return std::pair objects can be used to -populate a std::multimap, to allow entries to be looked -up by name. The string is initialised using the wxArchiveEntry object's -wxArchiveEntry::GetInternalName function. + Iterators that return std::pair objects can be used to + populate a std::multimap, to allow entries to be looked + up by name. The string is initialised using the wxArchiveEntry object's + wxArchiveEntry::GetInternalName function. -@code -typedef std::multimapwxString, wxZipEntry* ZipCatalog; -ZipCatalog cat((wxZipPairIter)zip, wxZipPairIter()); -@endcode + @code + typedef std::multimapwxString, wxZipEntry* ZipCatalog; + ZipCatalog cat((wxZipPairIter)zip, wxZipPairIter()); + @endcode -Note that this iterator also gives away ownership of an entry -object each time it is dereferenced. So in the above example, when -you have finished with @e cat you must delete the pointers it contains. + Note that this iterator also gives away ownership of an entry + object each time it is dereferenced. So in the above example, when + you have finished with @e cat you must delete the pointers it contains. -Or if you have them, a pair containing a smart pointer can be used -(again @e ZipEntryPtr), no worries about ownership: + Or if you have them, a pair containing a smart pointer can be used + (again @e ZipEntryPtr), no worries about ownership: -@code -typedef std::multimapwxString, ZipEntryPtr ZipCatalog; -typedef wxArchiveIteratorwxZipInputStream, -std::pairwxString, ZipEntryPtr ZipPairIter; -ZipCatalog cat((ZipPairIter)zip, ZipPairIter()); -@endcode + @code + typedef std::multimapwxString, ZipEntryPtr ZipCatalog; + typedef wxArchiveIteratorwxZipInputStream, + std::pairwxString, ZipEntryPtr ZipPairIter; + ZipCatalog cat((ZipPairIter)zip, ZipPairIter()); + @endcode -@library{wxbase} -@category{FIXME} + @library{wxbase} + @category{FIXME} -@seealso -wxArchiveEntry, wxArchiveInputStream, wxArchiveOutputStream + @seealso + wxArchiveEntry, wxArchiveInputStream, wxArchiveOutputStream */ class wxArchiveIterator { public: -//@{ -/** -Construct iterator that returns all the entries in the archive input -stream @e arc. -*/ -wxArchiveIterator(); -wxArchiveIterator(Arc& arc); -//@} + //@{ + /** + Construct iterator that returns all the entries in the archive input + stream @e arc. + */ + wxArchiveIterator(); + wxArchiveIterator(Arc& arc); + //@} -/** -Returns an entry object from the archive input stream, giving away -ownership. -*/ -const T operator*(); + /** + Returns an entry object from the archive input stream, giving away + ownership. + */ + const T operator*(); -//@{ -/** -Position the input iterator at the next entry in the archive input stream. -*/ -wxArchiveIterator operator++(); -wxArchiveIterator operator++(int ); -//@} + //@{ + /** + Position the input iterator at the next entry in the archive input stream. + */ + wxArchiveIterator operator++(); + wxArchiveIterator operator++(int ); + //@} }; diff --git a/interface/arrstr.h b/interface/arrstr.h index 46c5b27dfe..d71cc78b60 100644 --- a/interface/arrstr.h +++ b/interface/arrstr.h @@ -60,7 +60,7 @@ class wxArrayString : public wxArray public: //@{ /** - Constructor from a wxString array. Pass a size @e sz and array @e arr. + Constructor from a wxString array. Pass a size @a sz and array @e arr. */ wxArrayString(); wxArrayString(const wxArrayString& array); @@ -76,30 +76,26 @@ public: ~wxArrayString(); /** - Appends the given number of @e copies of the new item @e str to the + Appends the given number of @a copies of the new item @a str to the array and returns the index of the first new item in the array. - @b Warning: For sorted arrays, the index of the inserted item will not be, in general, equal to GetCount() - 1 because the item is inserted at the correct position to keep the array sorted and not appended. - See also: Insert() */ -#define size_t Add(const wxString& str, size_t copies = 1) /* implementation is private */ + size_t Add(const wxString& str, size_t copies = 1); /** - Preallocates enough memory to store @e nCount items. This function may be + Preallocates enough memory to store @a nCount items. This function may be used to improve array class performance before adding a known number of items consecutively. - See also: @ref wxArray::memorymanagement "Dynamic array memory management" */ void Alloc(size_t nCount); /** Clears the array contents and frees memory. - See also: Empty() */ void Clear(); @@ -121,25 +117,23 @@ public: /** Search the element in the array, starting from the beginning if - @e bFromEnd is @false or from end otherwise. If @e bCase, comparison is + @a bFromEnd is @false or from end otherwise. If @e bCase, comparison is case sensitive (default), otherwise the case is ignored. - This function uses linear search for wxArrayString and binary search for - wxSortedArrayString, but it ignores the @e bCase and @e bFromEnd + wxSortedArrayString, but it ignores the @a bCase and @a bFromEnd parameters in the latter case. - Returns index of the first item matched or @c wxNOT_FOUND if there is no match. */ - int Index(const wxString& sz, bool bCase = @true, - bool bFromEnd = @false); + int Index(const wxString& sz, bool bCase = true, + bool bFromEnd = false); /** - Insert the given number of @e copies of the new element in the array before the + Insert the given number of @a copies of the new element in the array before the position @e nIndex. Thus, for example, to insert the string in the beginning of the array you would write - If @e nIndex is equal to @e GetCount() this function behaves as - Add(). + If @a nIndex is equal to @e GetCount() this function behaves as + Add(). @b Warning: this function should not be used with sorted arrays because it could break the order of items and, for example, subsequent calls to Index() would then not work! @@ -157,7 +151,6 @@ public: Return the array element at position @e nIndex. An assert failure will result from an attempt to access an element beyond the end of array in debug mode, but no check is done in release mode. - See also @ref operatorindex() operator[] for the operator version. */ @@ -173,20 +166,18 @@ public: /** Removes the first item matching this value. An assert failure is provoked by an attempt to remove an element which does not exist in debug build. - See also: Index() */ void Remove(const wxString& sz); /** - Removes @e count items starting at position @e nIndex from the array. + Removes @a count items starting at position @a nIndex from the array. */ void RemoveAt(size_t nIndex, size_t count = 1); /** Releases the extra memory allocated by the array. This function is useful to minimize the array memory consumption. - See also: Alloc(), @ref wxArray::memorymanagement "Dynamic array memory management" */ @@ -194,13 +185,13 @@ public: //@{ /** - Sorts the array using the specified @e compareFunction for item comparison. + Sorts the array using the specified @a compareFunction for item comparison. @e CompareFunction is defined as a function taking two @e const wxString parameters and returning an @e int value less than, equal to or greater than 0 if the first string is less than, equal to or greater than the second one. */ - void Sort(bool reverseOrder = @false); + void Sort(bool reverseOrder = false); Warning: void Sort(CompareFunction compareFunction); //@} @@ -226,7 +217,6 @@ Warning: Return the array element at position @e nIndex. An assert failure will result from an attempt to access an element beyond the end of array in debug mode, but no check is done in release mode. - This is the operator version of Item() method. */ wxString operator[](size_t nIndex); @@ -238,30 +228,27 @@ Warning: // ============================================================================ /** - Splits the given wxString object using the separator @e sep and returns the + Splits the given wxString object using the separator @a sep and returns the result as a wxArrayString. - - If the @e escape character is non-@NULL, then the occurrences of @e sep + If the @a escape character is non-@NULL, then the occurrences of @a sep immediately prefixed - with @e escape are not considered as separators. - + with @a escape are not considered as separators. Note that empty tokens will be generated if there are two or more adjacent separators. - @sa wxJoin + @see wxJoin */ wxArrayString wxSplit(const wxString& str, const wxChar sep, const wxChar escape = ' '); /** - Concatenate all lines of the given wxArrayString object using the separator @e + Concatenate all lines of the given wxArrayString object using the separator @a sep and returns the result as a wxString. - - If the @e escape character is non-@NULL, then it's used as prefix for each + If the @a escape character is non-@NULL, then it's used as prefix for each occurrence of @e sep - in the strings contained in @e arr before joining them which is necessary + in the strings contained in @a arr before joining them which is necessary in order to be able to recover the original array contents from the string later using wxSplit. */ diff --git a/interface/artprov.h b/interface/artprov.h index b54939e512..91660de670 100644 --- a/interface/artprov.h +++ b/interface/artprov.h @@ -144,7 +144,6 @@ public: Client is the entity that calls wxArtProvider's GetBitmap or GetIcon function. It is represented by wxClientID type and can have one of these values: - wxART_TOOLBAR wxART_MENU wxART_BUTTON @@ -154,7 +153,6 @@ public: wxART_MESSAGE_BOX wxART_OTHER (used for all requests that don't fit into any of the categories above) - Client ID servers as a hint to wxArtProvider that is supposed to help it to choose the best looking bitmap. For example it is often desirable to use slightly different icons in menus and toolbars even though they represent the @@ -163,7 +161,7 @@ public: GetBitmap() returns identical bitmap for different @e client values! - @sa See the artprov sample for an example of wxArtProvider usage. + @see See the artprov sample for an example of wxArtProvider usage. */ @@ -174,17 +172,15 @@ public: create wxBitmap objects from XPMs here). @param id - wxArtID unique identifier of the bitmap. - + wxArtID unique identifier of the bitmap. @param client - wxArtClient identifier of the client (i.e. who is asking for the bitmap). - This only servers as a hint. - + wxArtClient identifier of the client (i.e. who is asking for the bitmap). + This only servers as a hint. @param size - Preferred size of the bitmap. The function may return a bitmap of different - dimensions, it will be automatically rescaled to meet client's request. + Preferred size of the bitmap. The function may return a bitmap of different + dimensions, it will be automatically rescaled to meet client's request. - @sa CreateIconBundle() + @see CreateIconBundle() */ wxBitmap CreateBitmap(const wxArtID& id, const wxArtClient& client, @@ -206,16 +202,14 @@ public: Query registered providers for bitmap with given ID. @param id - wxArtID unique identifier of the bitmap. - + wxArtID unique identifier of the bitmap. @param client - wxArtClient identifier of the client (i.e. who is asking for the bitmap). - + wxArtClient identifier of the client (i.e. who is asking for the bitmap). @param size - Size of the returned bitmap or wxDefaultSize if size doesn't matter. + Size of the returned bitmap or wxDefaultSize if size doesn't matter. @returns The bitmap if one of registered providers recognizes the ID or - wxNullBitmap otherwise. + wxNullBitmap otherwise. */ static wxBitmap GetBitmap(const wxArtID& id, const wxArtClient& client = wxART_OTHER, @@ -224,7 +218,7 @@ public: //@{ /** Returns a suitable size hint for the given @e wxArtClient. If - @e platform_default is @true, return a size based on the current platform, + @a platform_default is @true, return a size based on the current platform, otherwise return the size from the topmost wxArtProvider. @e wxDefaultSize may be returned if the client doesn't have a specified size, like wxART_OTHER for @@ -234,20 +228,20 @@ public: const wxArtClient& client = wxART_OTHER, const wxSize& size = wxDefaultSize); static wxSize GetSizeHint(const wxArtClient& client, - bool platform_default = @false); + bool platform_default = false); //@} /** Query registered providers for icon bundle with given ID. @param id - wxArtID unique identifier of the icon bundle. - + wxArtID unique identifier of the icon bundle. @param client - wxArtClient identifier of the client (i.e. who is asking for the icon bundle). + wxArtClient identifier of the client (i.e. who is asking for the icon + bundle). @returns The icon bundle if one of registered providers recognizes the ID - or wxNullIconBundle otherwise. + or wxNullIconBundle otherwise. */ static wxIconBundle GetIconBundle(const wxArtID& id, const wxArtClient& client = wxART_OTHER); @@ -307,7 +301,6 @@ public: wxART_FLOPPY wxART_CDROM wxART_REMOVABLE - Additionally, any string recognized by custom art providers registered using Push() may be used. */ @@ -317,20 +310,20 @@ public: Register new art provider and add it to the bottom of providers stack (i.e. it will be queried as the last one). - @sa Push() + @see Push() */ static void Insert(wxArtProvider* provider); /** Remove latest added provider and delete it. */ -#define static bool Pop() /* implementation is private */ + static bool Pop(); /** Register new art provider and add it to the top of providers stack (i.e. it will be queried as the first provider). - @sa Insert() + @see Insert() */ static void Push(wxArtProvider* provider); diff --git a/interface/atomic.h b/interface/atomic.h index 6849d00675..ee07a6636e 100644 --- a/interface/atomic.h +++ b/interface/atomic.h @@ -7,7 +7,7 @@ ///////////////////////////////////////////////////////////////////////////// /** -This function increments @e value in an atomic manner. +This function increments @a value in an atomic manner. */ void wxAtomicInc(wxAtomicInt& value); diff --git a/interface/aui/aui.h b/interface/aui/aui.h index 46a55a4553..174bbc79dc 100644 --- a/interface/aui/aui.h +++ b/interface/aui/aui.h @@ -12,7 +12,7 @@ wxAuiManager is the central class of the wxAUI class framework. - See also @ref overview_wxauioverview "wxAUI overview". + See also @ref overview_wxauioverview. wxAuiManager manages the panes associated with it for a particular wxFrame, using a pane's wxAuiPaneInfo information to @@ -56,11 +56,11 @@ class wxAuiManager : public wxEvtHandler { public: /** - Constructor. @e managed_wnd specifies the wxFrame which should be managed. - @e flags specifies options which allow the frame management behavior + Constructor. @a managed_wnd specifies the wxFrame which should be managed. + @a flags specifies options which allow the frame management behavior to be modified. */ - wxAuiManager(wxWindow* managed_wnd = @NULL, + wxAuiManager(wxWindow* managed_wnd = NULL, unsigned int flags = wxAUI_MGR_DEFAULT); /** @@ -95,7 +95,6 @@ public: /** Returns the current art provider being used. - See also: wxAuiDockArt. */ wxAuiDockArt* GetArtProvider(); @@ -117,11 +116,11 @@ public: wxWindow* GetManagedWindow(); /** - Calling this method will return the wxAuiManager for a given window. The @e + Calling this method will return the wxAuiManager for a given window. The @a window parameter should specify any child window or sub-child window of the frame or window managed by wxAuiManager. - The @e window parameter need not be managed by the manager itself, nor does it + The @a window parameter need not be managed by the manager itself, nor does it even need to be a child or sub-child of a managed window. It must however be inside the window hierarchy underneath the managed @@ -154,9 +153,9 @@ public: into the frame manager, or to insert a currently managed pane somewhere else. @e InsertPane will push all panes, rows, or docks aside and insert the window into the position specified by @e insert_location. - Because @e insert_location can specify either a pane, dock row, or dock - layer, the @e insert_level parameter is used to disambiguate this. The - parameter @e insert_level can take a value of wxAUI_INSERT_PANE, + Because @a insert_location can specify either a pane, dock row, or dock + layer, the @a insert_level parameter is used to disambiguate this. The + parameter @a insert_level can take a value of wxAUI_INSERT_PANE, wxAUI_INSERT_ROW or wxAUI_INSERT_DOCK. */ @@ -175,7 +174,7 @@ public: is automatically invoked, thus realizing the saved perspective on screen. */ bool LoadPerspective(const wxString& perspective, - bool update = @true); + bool update = true); /** ProcessDockResult() is a protected member of the wxAUI layout manager. It can @@ -200,10 +199,9 @@ public: /** Instructs wxAuiManager to use art provider specified by parameter - @e art_provider for all drawing calls. This allows plugable + @a art_provider for all drawing calls. This allows plugable look-and-feel features. The previous art provider object, if any, will be deleted by wxAuiManager. - See also: wxAuiDockArt. */ void SetArtProvider(wxAuiDockArt* art_provider); @@ -265,7 +263,7 @@ public: @headerfile aui.h wx/aui/aui.h wxAuiPaneInfo is part of the wxAUI class framework. - See also @ref overview_wxauioverview "wxAUI overview". + See also @ref overview_wxauioverview. wxAuiPaneInfo specifies all the parameters for a pane. These parameters specify where the pane is on the @@ -310,7 +308,7 @@ public: BottomDockable() indicates whether a pane can be docked at the bottom of the frame. */ - wxAuiPaneInfo BottomDockable(bool b = @true); + wxAuiPaneInfo BottomDockable(bool b = true); /** Caption() sets the caption of the pane. @@ -321,14 +319,13 @@ public: CaptionVisible indicates that a pane caption should be visible. If @false, no pane caption is drawn. */ - wxAuiPaneInfo CaptionVisible(bool visible = @true); + wxAuiPaneInfo CaptionVisible(bool visible = true); //@{ /** Center() sets the pane dock position to the left side of the frame. The centre pane is the space in the middle after all border panes (left, top, right, bottom) are subtracted from the layout. - This is the same thing as calling Direction(wxAUI_DOCK_CENTRE). */ wxAuiPaneInfo Centre(); @@ -347,7 +344,7 @@ public: /** CloseButton() indicates that a close button should be drawn for the pane. */ - wxAuiPaneInfo CloseButton(bool visible = @true); + wxAuiPaneInfo CloseButton(bool visible = true); /** DefaultPane() specifies that the pane should adopt the default pane settings. @@ -358,7 +355,7 @@ public: DestroyOnClose() indicates whether a pane should be detroyed when it is closed. Normally a pane is simply hidden when the close button is clicked. Setting DestroyOnClose to @true will cause the window to be destroyed when the user clicks the pane's close button. */ - wxAuiPaneInfo DestroyOnClose(bool b = @true); + wxAuiPaneInfo DestroyOnClose(bool b = true); /** Direction() determines the direction of the docked pane. It is functionally the @@ -375,13 +372,13 @@ public: DockFixed() causes the containing dock to have no resize sash. This is useful for creating panes that span the entire width or height of a dock, but should not be resizable in the other direction. */ - wxAuiPaneInfo DockFixed(bool b = @true); + wxAuiPaneInfo DockFixed(bool b = true); /** Dockable() specifies whether a frame can be docked or not. It is the same as specifying TopDockable(b).BottomDockable(b).LeftDockable(b).RightDockable(b). */ - wxAuiPaneInfo Dockable(bool b = @true); + wxAuiPaneInfo Dockable(bool b = true); /** Fixed() forces a pane to be fixed size so that it cannot be resized. After @@ -398,7 +395,7 @@ public: Floatable() sets whether the user will be able to undock a pane and turn it into a floating window. */ - wxAuiPaneInfo Floatable(bool b = @true); + wxAuiPaneInfo Floatable(bool b = true); //@{ /** @@ -419,12 +416,12 @@ public: /** Gripper() indicates that a gripper should be drawn for the pane. */ - wxAuiPaneInfo Gripper(bool visible = @true); + wxAuiPaneInfo Gripper(bool visible = true); /** GripperTop() indicates that a gripper should be drawn at the top of the pane. */ - wxAuiPaneInfo GripperTop(bool attop = @true); + wxAuiPaneInfo GripperTop(bool attop = true); /** HasBorder() returns @true if the pane displays a border. @@ -522,7 +519,7 @@ public: IsOk() returns @true if the wxAuiPaneInfo structure is valid. A pane structure is valid if it has an associated window. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** IsResizable() returns @true if the pane can be resized. @@ -566,7 +563,7 @@ public: /** LeftDockable() indicates whether a pane can be docked on the left of the frame. */ - wxAuiPaneInfo LeftDockable(bool b = @true); + wxAuiPaneInfo LeftDockable(bool b = true); //@{ /** @@ -579,7 +576,7 @@ public: /** MaximizeButton() indicates that a maximize button should be drawn for the pane. */ - wxAuiPaneInfo MaximizeButton(bool visible = @true); + wxAuiPaneInfo MaximizeButton(bool visible = true); //@{ /** @@ -593,12 +590,12 @@ public: /** MinimizeButton() indicates that a minimize button should be drawn for the pane. */ - wxAuiPaneInfo MinimizeButton(bool visible = @true); + wxAuiPaneInfo MinimizeButton(bool visible = true); /** Movable indicates whether a frame can be moved. */ - wxAuiPaneInfo Movable(bool b = @true); + wxAuiPaneInfo Movable(bool b = true); /** Name() sets the name of the pane so it can be referenced in lookup functions. @@ -609,12 +606,12 @@ public: /** PaneBorder indicates that a border should be drawn for the pane. */ - wxAuiPaneInfo PaneBorder(bool visible = @true); + wxAuiPaneInfo PaneBorder(bool visible = true); /** PinButton() indicates that a pin button should be drawn for the pane. */ - wxAuiPaneInfo PinButton(bool visible = @true); + wxAuiPaneInfo PinButton(bool visible = true); /** Position() determines the position of the docked pane. @@ -625,7 +622,7 @@ public: Resizable() allows a pane to be resized if the parameter is @true, and forces it to be a fixed size if the parameter is @false. This is simply an antonym for Fixed(). */ - wxAuiPaneInfo Resizable(bool resizable = @true); + wxAuiPaneInfo Resizable(bool resizable = true); /** Right() sets the pane dock position to the right side of the frame. @@ -636,12 +633,12 @@ public: RightDockable() indicates whether a pane can be docked on the right of the frame. */ - wxAuiPaneInfo RightDockable(bool b = @true); + wxAuiPaneInfo RightDockable(bool b = true); /** Row() determines the row of the docked pane. */ -#define wxAuiPaneInfo Row(int row) /* implementation is private */ + wxAuiPaneInfo Row(int row); /** Write the safe parts of a newly loaded PaneInfo structure "source" into "this" @@ -658,7 +655,7 @@ public: /** Show() indicates that a pane should be shown. */ - wxAuiPaneInfo Show(bool show = @true); + wxAuiPaneInfo Show(bool show = true); /** ToolbarPane() specifies that the pane should adopt the default toolbar pane @@ -669,12 +666,12 @@ public: /** Top() sets the pane dock position to the top of the frame. */ -#define wxAuiPaneInfo Top() /* implementation is private */ + wxAuiPaneInfo Top(); /** TopDockable() indicates whether a pane can be docked at the top of the frame. */ - wxAuiPaneInfo TopDockable(bool b = @true); + wxAuiPaneInfo TopDockable(bool b = true); /** Window() assigns the window pointer that the wxAuiPaneInfo should use. This diff --git a/interface/aui/auibook.h b/interface/aui/auibook.h index 79a08fa55e..b8a6110dbd 100644 --- a/interface/aui/auibook.h +++ b/interface/aui/auibook.h @@ -11,7 +11,7 @@ @headerfile auibook.h wx/aui/auibook.h wxAuiNotebook is part of the wxAUI class framework. - See also @ref overview_wxauioverview "wxAUI overview". + See also @ref overview_wxauioverview. wxAuiNotebook is a notebook control which implements many features common in applications with dockable panes. @@ -74,17 +74,17 @@ public: //@} /** - Adds a page. If the @e select parameter is @true, calling this will generate a + Adds a page. If the @a select parameter is @true, calling this will generate a page change event. */ bool AddPage(wxWindow* page, const wxString& caption, - bool select = @false, + bool select = false, const wxBitmap& bitmap = wxNullBitmap); /** Sets the selection to the next or previous page. */ - void AdvanceSelection(bool forward = @true); + void AdvanceSelection(bool forward = true); /** Creates the notebook window. @@ -151,12 +151,12 @@ public: /** InsertPage() is similar to AddPage, but allows the ability to specify the insert location. - If the @e select parameter is @true, calling this will generate a page change + If the @a select parameter is @true, calling this will generate a page change event. */ bool InsertPage(size_t page_idx, wxWindow* page, const wxString& caption, - bool select = @false, + bool select = false, const wxBitmap& bitmap = wxNullBitmap); /** @@ -219,11 +219,11 @@ public: //@{ /** - Split performs a split operation programmatically. The argument @e page + Split performs a split operation programmatically. The argument @a page indicates the page that will be split off. This page will also become the active page after the - split. The @e direction argument specifies where the pane should go, it should + split. The @a direction argument specifies where the pane should go, it should be one of the following: wxTOP, wxBOTTOM, wxLEFT, or wxRIGHT. */ diff --git a/interface/aui/dockart.h b/interface/aui/dockart.h index 118eebd573..f9a85a1826 100644 --- a/interface/aui/dockart.h +++ b/interface/aui/dockart.h @@ -11,7 +11,7 @@ @headerfile dockart.h wx/aui/dockart.h wxAuiDockArt is part of the wxAUI class framework. - See also @ref overview_wxauioverview "wxAUI overview". + See also @ref overview_wxauioverview. Dock art provider code - a dock provider provides all drawing functionality to the wxAui dock manager. This allows the dock @@ -75,10 +75,8 @@ public: /** Draws a button in the pane's title bar. - - @e button can be one of the values of @b wxAuiButtonId. - - @e button_state can be one of the values of @b wxAuiPaneButtonState. + @a button can be one of the values of @b wxAuiButtonId. + @a button_state can be one of the values of @b wxAuiPaneButtonState. */ virtual void DrawPaneButton(wxDC& dc, wxWindow* window, int button, @@ -100,8 +98,7 @@ public: /** Get the colour of a certain setting. - - @e id can be one of the colour values of @b wxAuiPaneDockArtSetting. + @a id can be one of the colour values of @b wxAuiPaneDockArtSetting. */ virtual wxColour GetColour(int id); @@ -112,8 +109,7 @@ public: /** Get the value of a certain setting. - - @e id can be one of the size values of @b wxAuiPaneDockArtSetting. + @a id can be one of the size values of @b wxAuiPaneDockArtSetting. */ virtual int GetMetric(int id); @@ -124,8 +120,7 @@ public: /** Set a certain setting with the value @e colour. - - @e id can be one of the colour values of @b wxAuiPaneDockArtSetting. + @a id can be one of the colour values of @b wxAuiPaneDockArtSetting. */ virtual void SetColour(int id, const wxColor& colour); @@ -136,8 +131,7 @@ public: /** Set a certain setting with the value @e new_val. - - @e id can be one of the size values of @b wxAuiPaneDockArtSetting. + @a id can be one of the size values of @b wxAuiPaneDockArtSetting. */ virtual void SetMetric(int id, int new_val); }; diff --git a/interface/base64.h b/interface/base64.h index 201fa3c634..388ac189cf 100644 --- a/interface/base64.h +++ b/interface/base64.h @@ -14,25 +14,22 @@ functions except for the first one which returns @c wxCONV_FAILED if the output buffer is too small. To allocate the buffer of the correct size, use wxBase64EncodedSize or call this function with - @e dst set to @NULL -- it will then return the necessary buffer size. + @a dst set to @NULL -- it will then return the necessary buffer size. @param dst - The output buffer, may be @NULL to retrieve the needed buffer - size. - + The output buffer, may be @NULL to retrieve the needed buffer + size. @param dstLen - The output buffer size, ignored if dst is @NULL. - + The output buffer size, ignored if dst is @NULL. @param src - The input buffer, must not be @NULL. - + The input buffer, must not be @NULL. @param srcLen - The length of the input data. + The length of the input data. */ -size_t wxBase64Encode(char * dst, size_t dstLen, - const void * src, +size_t wxBase64Encode(char* dst, size_t dstLen, + const void* src, size_t srcLen); -wxString wxBase64Encode(const void * src, size_t srcLen); +wxString wxBase64Encode(const void* src, size_t srcLen); wxString wxBase64Encode(const wxMemoryBuffer& buf); //@} @@ -54,58 +51,54 @@ size_t wxBase64EncodedSize(size_t len); //@{ /** These function decode a Base64-encoded string. The first version is a raw - decoding function and decodes the data into the provided buffer @e dst of + decoding function and decodes the data into the provided buffer @a dst of the given size @e dstLen. An error is returned if the buffer is not large enough -- that is not at least wxBase64DecodedSize(srcLen) bytes. The second version allocates memory internally and returns it as wxMemoryBuffer and is recommended for normal use. - The first version returns the number of bytes written to the buffer or the - necessary buffer size if @e dst was @NULL or @c wxCONV_FAILED on + necessary buffer size if @a dst was @NULL or @c wxCONV_FAILED on error, e.g. if the output buffer is too small or invalid characters were encountered in the input string. The second version returns a buffer with the base64 decoded binary equivalent of the input string. In neither case is the buffer NUL-terminated. @param dst - Pointer to output buffer, may be @NULL to just compute the - necessary buffer size. - + Pointer to output buffer, may be @NULL to just compute the + necessary buffer size. @param dstLen - The size of the output buffer, ignored if dst is - @NULL. - + The size of the output buffer, ignored if dst is + @NULL. @param src - The input string, must not be @NULL. For the version using - wxString, the input string should contain only ASCII characters. - + The input string, must not be @NULL. For the version using + wxString, the input string should contain only ASCII characters. @param srcLen - The length of the input string or special value - wxNO_LEN if the string is NUL-terminated and the length should be - computed by this function itself. - + The length of the input string or special value + wxNO_LEN if the string is NUL-terminated and the length should be + computed by this function itself. @param mode - This parameter specifies the function behaviour when invalid - characters are encountered in input. By default, any such character stops the - decoding with error. If the mode is wxBase64DecodeMode_SkipWS, then the white - space characters are silently skipped instead. And if it is - wxBase64DecodeMode_Relaxed, then all invalid characters are skipped. - + This parameter specifies the function behaviour when invalid + characters are encountered in input. By default, any such character stops + the + decoding with error. If the mode is wxBase64DecodeMode_SkipWS, then the + white + space characters are silently skipped instead. And if it is + wxBase64DecodeMode_Relaxed, then all invalid characters are skipped. @param posErr - If this pointer is non-@NULL and an error occurs during - decoding, it is filled with the index of the invalid character. + If this pointer is non-@NULL and an error occurs during + decoding, it is filled with the index of the invalid character. */ -size_t wxBase64Decode(void * dst, size_t dstLen, - const char * src, +size_t wxBase64Decode(void* dst, size_t dstLen, + const char* src, size_t srcLen = wxNO_LEN, wxBase64DecodeMode mode = wxBase64DecodeMode_Strict, - size_t posErr = @NULL); -wxMemoryBuffer wxBase64Decode(const char * src, + size_t posErr = NULL); +wxMemoryBuffer wxBase64Decode(const char* src, size_t srcLen = wxNO_LEN, wxBase64DecodeMode mode = wxBase64DecodeMode_Strict, - size_t posErr = @NULL); + size_t posErr = NULL); wxMemoryBuffer wxBase64Decode(const wxString& src, wxBase64DecodeMode mode = wxBase64DecodeMode_Strict, - size_t posErr = @NULL); + size_t posErr = NULL); //@} diff --git a/interface/bitmap.h b/interface/bitmap.h index 49a97e2349..a8aff7efe0 100644 --- a/interface/bitmap.h +++ b/interface/bitmap.h @@ -43,27 +43,22 @@ public: /** Creates a bitmap from the given data, which can be of arbitrary type. The - wxBitmap object @e bitmap is + wxBitmap object @a bitmap is manipulated by this function. @param bitmap - The wxBitmap object. - + The wxBitmap object. @param width - The width of the bitmap in pixels. - + The width of the bitmap in pixels. @param height - The height of the bitmap in pixels. - + The height of the bitmap in pixels. @param depth - The depth of the bitmap in pixels. If this is -1, the screen depth is used. - + The depth of the bitmap in pixels. If this is -1, the screen depth is used. @param data - Data whose type depends on the value of type. - + Data whose type depends on the value of type. @param type - A bitmap type identifier - see wxBitmapHandler() for a list - of possible values. + A bitmap type identifier - see wxBitmapHandler() for a list + of possible values. @returns @true if the call succeeded, @false otherwise (the default). */ @@ -92,18 +87,16 @@ public: bitmap. @param bitmap - The bitmap object which is to be affected by this operation. - + The bitmap object which is to be affected by this operation. @param name - Either a filename or a Windows resource name. - The meaning of name is determined by the type parameter. - + Either a filename or a Windows resource name. + The meaning of name is determined by the type parameter. @param type - See wxBitmap::wxBitmap for values this can take. + See wxBitmap::wxBitmap for values this can take. @returns @true if the operation succeeded, @false otherwise. - @sa wxBitmap::LoadFile, wxBitmap::SaveFile, SaveFile() + @see wxBitmap::LoadFile, wxBitmap::SaveFile, SaveFile() */ bool LoadFile(wxBitmap* bitmap, const wxString& name, long type); @@ -111,29 +104,26 @@ public: Saves a bitmap in the named file. @param bitmap - The bitmap object which is to be affected by this operation. - + The bitmap object which is to be affected by this operation. @param name - A filename. The meaning of name is determined by the type parameter. - + A filename. The meaning of name is determined by the type parameter. @param type - See wxBitmap::wxBitmap for values this can take. - + See wxBitmap::wxBitmap for values this can take. @param palette - An optional palette used for saving the bitmap. + An optional palette used for saving the bitmap. @returns @true if the operation succeeded, @false otherwise. - @sa wxBitmap::LoadFile, wxBitmap::SaveFile, LoadFile() + @see wxBitmap::LoadFile, wxBitmap::SaveFile, LoadFile() */ bool SaveFile(wxBitmap* bitmap, const wxString& name, int type, - wxPalette* palette = @NULL); + wxPalette* palette = NULL); /** Sets the handler extension. @param extension - Handler extension. + Handler extension. */ void SetExtension(const wxString& extension); @@ -141,7 +131,7 @@ public: Sets the handler name. @param name - Handler name. + Handler name. */ void SetName(const wxString& name); @@ -149,7 +139,7 @@ public: Sets the handler type. @param name - Handler type. + Handler type. */ void SetType(long type); }; @@ -183,92 +173,127 @@ public: The resulting bitmap will use the provided colour depth (or that of the current system if depth is -1) which entails that a colour reduction has to take place. - When in 8-bit mode (PseudoColour mode), the GTK port will use a color cube created on program start-up to look up colors. This ensures a very fast conversion, but the image quality won't be perfect (and could be better for photo images using more sophisticated dithering algorithms). - On Windows, if there is a palette present (set with SetPalette), it will be used when creating the wxBitmap (most useful in 8-bit display mode). On other platforms, the palette is currently ignored. @param bits - Specifies an array of pixel values. - + Specifies an array of pixel values. @param width - Specifies the width of the bitmap. - + Specifies the width of the bitmap. @param height - Specifies the height of the bitmap. - + Specifies the height of the bitmap. @param depth - Specifies the depth of the bitmap. If this is omitted, the display depth of the - screen is used. - + Specifies the depth of the bitmap. If this is omitted, the display depth of + the + screen is used. @param name - This can refer to a resource name under MS Windows, or a filename under MS + This can refer to a resource name under MS Windows, or a filename under MS Windows and X. - Its meaning is determined by the type parameter. - + Its meaning is determined by the type parameter. @param type - May be one of the following: + May be one of the following: + + + + + + + + wxBITMAP_TYPE_BMP + + + + + Load a Windows bitmap file. + + + + + + wxBITMAP_TYPE_BMP_RESOURCE + + - wxBITMAP_TYPE_BMP + Load a Windows bitmap resource from the executable. Windows only. - Load a Windows bitmap file. - wxBITMAP_TYPE_BMP_RESOURCE - Load a Windows bitmap resource from the executable. Windows only. + wxBITMAP_TYPE_PICT_RESOURCE - wxBITMAP_TYPE_PICT_RESOURCE - Load a PICT image resource from the executable. Mac OS only. - wxBITMAP_TYPE_GIF + Load a PICT image resource from the executable. Mac OS only. - Load a GIF bitmap file. - wxBITMAP_TYPE_XBM - Load an X bitmap file. + wxBITMAP_TYPE_GIF - wxBITMAP_TYPE_XPM - Load an XPM bitmap file. - The validity of these flags depends on the platform and wxWidgets configuration. - If all possible wxWidgets settings are used, the Windows platform supports BMP - file, BMP resource, - XPM data, and XPM. Under wxGTK, the available formats are BMP file, XPM data, - XPM file, and PNG file. - Under wxMotif, the available formats are XBM data, XBM file, XPM data, XPM file. + Load a GIF bitmap file. - In addition, wxBitmap can read all formats that wxImage can, which currently - include - wxBITMAP_TYPE_JPEG, wxBITMAP_TYPE_TIF, wxBITMAP_TYPE_PNG, wxBITMAP_TYPE_GIF, - wxBITMAP_TYPE_PCX, - and wxBITMAP_TYPE_PNM. Of course, you must have wxImage handlers loaded. + + + + wxBITMAP_TYPE_XBM + + + + + Load an X bitmap file. + + + + + + wxBITMAP_TYPE_XPM + + + + + Load an XPM bitmap file. + + + + + + The validity of these flags depends on the platform and wxWidgets + configuration. + If all possible wxWidgets settings are used, the Windows platform supports + BMP file, BMP resource, + XPM data, and XPM. Under wxGTK, the available formats are BMP file, XPM + data, XPM file, and PNG file. + Under wxMotif, the available formats are XBM data, XBM file, XPM data, XPM + file. + In addition, wxBitmap can read all formats that wxImage can, which + currently include + wxBITMAP_TYPE_JPEG, wxBITMAP_TYPE_TIF, wxBITMAP_TYPE_PNG, + wxBITMAP_TYPE_GIF, wxBITMAP_TYPE_PCX, + and wxBITMAP_TYPE_PNM. Of course, you must have wxImage handlers loaded. @param img - Platform-independent wxImage object. + Platform-independent wxImage object. @remarks The first form constructs a bitmap object with no data; an - assignment or another member function such as Create - or LoadFile must be called subsequently. + assignment or another member function such as Create or + LoadFile must be called subsequently. - @sa LoadFile() + @see LoadFile() */ wxBitmap(); wxBitmap(const wxBitmap& bitmap); @@ -286,10 +311,8 @@ public: Destructor. See @ref overview_refcountdestruct "reference-counted object destruction" for more info. - If the application omits to delete the bitmap explicitly, the bitmap will be destroyed automatically by wxWidgets when the application exits. - Do not delete a bitmap that is selected into a memory device context. */ ~wxBitmap(); @@ -298,16 +321,15 @@ public: Adds a handler to the end of the static list of format handlers. @param handler - A new bitmap format handler object. There is usually only one instance - of a given handler class in an application session. + A new bitmap format handler object. There is usually only one instance + of a given handler class in an application session. - @sa wxBitmapHandler + @see wxBitmapHandler */ static void AddHandler(wxBitmapHandler* handler); /** Deletes all bitmap handlers. - This function is called by wxWidgets on exit. */ static void CleanUpHandlers(); @@ -329,27 +351,23 @@ public: Creates a bitmap from the given data, which can be of arbitrary type. @param width - The width of the bitmap in pixels. - + The width of the bitmap in pixels. @param height - The height of the bitmap in pixels. - + The height of the bitmap in pixels. @param depth - The depth of the bitmap in pixels. If this is -1, the screen depth is used. - + The depth of the bitmap in pixels. If this is -1, the screen depth is used. @param data - Data whose type depends on the value of type. - + Data whose type depends on the value of type. @param type - A bitmap type identifier - see wxBitmap() for a list - of possible values. + A bitmap type identifier - see wxBitmap() for a list + of possible values. @returns @true if the call succeeded, @false otherwise. @remarks The first form works on all platforms. The portability of the - second form depends on the type of data. + second form depends on the type of data. - @sa wxBitmap() + @see wxBitmap() */ virtual bool Create(int width, int height, int depth = -1); virtual bool Create(const void* data, int type, int width, @@ -362,17 +380,15 @@ public: Finds the handler associated with the given bitmap type. @param name - The handler name. - + The handler name. @param extension - The file extension, such as "bmp". - + The file extension, such as "bmp". @param bitmapType - The bitmap type, such as wxBITMAP_TYPE_BMP. + The bitmap type, such as wxBITMAP_TYPE_BMP. @returns A pointer to the handler if found, @NULL otherwise. - @sa wxBitmapHandler + @see wxBitmapHandler */ static wxBitmapHandler* FindHandler(const wxString& name); static wxBitmapHandler* FindHandler(const wxString& extension, @@ -389,7 +405,7 @@ public: /** Returns the static list of bitmap format handlers. - @sa wxBitmapHandler + @see wxBitmapHandler */ static wxList GetHandlers(); @@ -402,7 +418,7 @@ public: Gets the associated mask (if any) which may have been loaded from a file or set for the bitmap. - @sa SetMask(), wxMask + @see SetMask(), wxMask */ wxMask* GetMask(); @@ -410,7 +426,7 @@ public: Gets the associated palette (if any) which may have been loaded from a file or set for the bitmap. - @sa wxPalette + @see wxPalette */ wxPalette* GetPalette(); @@ -423,7 +439,7 @@ public: /** Gets the width of the bitmap in pixels. - @sa GetHeight() + @see GetHeight() */ int GetWidth(); @@ -431,10 +447,9 @@ public: Adds the standard bitmap format handlers, which, depending on wxWidgets configuration, can be handlers for Windows bitmap, Windows bitmap resource, and XPM. - This function is called by wxWidgets on startup. - @sa wxBitmapHandler + @see wxBitmapHandler */ static void InitStandardHandlers(); @@ -442,74 +457,114 @@ public: Adds a handler at the start of the static list of format handlers. @param handler - A new bitmap format handler object. There is usually only one instance - of a given handler class in an application session. + A new bitmap format handler object. There is usually only one instance + of a given handler class in an application session. - @sa wxBitmapHandler + @see wxBitmapHandler */ static void InsertHandler(wxBitmapHandler* handler); /** Returns @true if bitmap data is present. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** Loads a bitmap from a file or resource. @param name - Either a filename or a Windows resource name. - The meaning of name is determined by the type parameter. - + Either a filename or a Windows resource name. + The meaning of name is determined by the type parameter. @param type - One of the following values: + One of the following values: + + + - wxBITMAP_TYPE_BMP - Load a Windows bitmap file. + wxBITMAP_TYPE_BMP - wxBITMAP_TYPE_BMP_RESOURCE - Load a Windows bitmap resource from the executable. - wxBITMAP_TYPE_PICT_RESOURCE + Load a Windows bitmap file. - Load a PICT image resource from the executable. Mac OS only. - wxBITMAP_TYPE_GIF - Load a GIF bitmap file. + wxBITMAP_TYPE_BMP_RESOURCE - wxBITMAP_TYPE_XBM - Load an X bitmap file. - wxBITMAP_TYPE_XPM + Load a Windows bitmap resource from the executable. - Load an XPM bitmap file. - The validity of these flags depends on the platform and wxWidgets configuration. - In addition, wxBitmap can read all formats that wxImage can - (wxBITMAP_TYPE_JPEG, wxBITMAP_TYPE_PNG, wxBITMAP_TYPE_GIF, wxBITMAP_TYPE_PCX, - wxBITMAP_TYPE_PNM). - (Of course you must have wxImage handlers loaded.) + + wxBITMAP_TYPE_PICT_RESOURCE + + + + + Load a PICT image resource from the executable. Mac OS only. + + + + + + wxBITMAP_TYPE_GIF + + + + + Load a GIF bitmap file. + + + + + + wxBITMAP_TYPE_XBM + + + + + Load an X bitmap file. + + + + + + wxBITMAP_TYPE_XPM + + + + + Load an XPM bitmap file. + + + + + + The validity of these flags depends on the platform and wxWidgets + configuration. + In addition, wxBitmap can read all formats that wxImage can + (wxBITMAP_TYPE_JPEG, wxBITMAP_TYPE_PNG, wxBITMAP_TYPE_GIF, + wxBITMAP_TYPE_PCX, wxBITMAP_TYPE_PNM). + (Of course you must have wxImage handlers loaded.) @returns @true if the operation succeeded, @false otherwise. @remarks A palette may be associated with the bitmap if one exists - (especially for colour Windows bitmaps), and if the - code supports it. You can check if one has been - created by using the GetPalette member. + (especially for colour Windows bitmaps), and if the + code supports it. You can check if one has been created + by using the GetPalette member. - @sa SaveFile() + @see SaveFile() */ bool LoadFile(const wxString& name, wxBitmapType type); @@ -518,11 +573,11 @@ public: is not deleted. @param name - The handler name. + The handler name. @returns @true if the handler was found and removed, @false otherwise. - @sa wxBitmapHandler + @see wxBitmapHandler */ static bool RemoveHandler(const wxString& name); @@ -530,56 +585,83 @@ public: Saves a bitmap in the named file. @param name - A filename. The meaning of name is determined by the type parameter. - + A filename. The meaning of name is determined by the type parameter. @param type - One of the following values: + One of the following values: + + + + + + + + wxBITMAP_TYPE_BMP + + + + + Save a Windows bitmap file. + + + - wxBITMAP_TYPE_BMP + wxBITMAP_TYPE_GIF - Save a Windows bitmap file. - wxBITMAP_TYPE_GIF + Save a GIF bitmap file. - Save a GIF bitmap file. - wxBITMAP_TYPE_XBM - Save an X bitmap file. - wxBITMAP_TYPE_XPM + wxBITMAP_TYPE_XBM - Save an XPM bitmap file. - The validity of these flags depends on the platform and wxWidgets configuration. - In addition, wxBitmap can save all formats that wxImage can - (wxBITMAP_TYPE_JPEG, wxBITMAP_TYPE_PNG). - (Of course you must have wxImage handlers loaded.) + Save an X bitmap file. + + + + + wxBITMAP_TYPE_XPM + + + + + Save an XPM bitmap file. + + + + + + The validity of these flags depends on the platform and wxWidgets + configuration. + In addition, wxBitmap can save all formats that wxImage can + (wxBITMAP_TYPE_JPEG, wxBITMAP_TYPE_PNG). + (Of course you must have wxImage handlers loaded.) @param palette - An optional palette used for saving the bitmap. + An optional palette used for saving the bitmap. @returns @true if the operation succeeded, @false otherwise. @remarks Depending on how wxWidgets has been configured, not all formats - may be available. + may be available. - @sa LoadFile() + @see LoadFile() */ bool SaveFile(const wxString& name, wxBitmapType type, - wxPalette* palette = @NULL); + wxPalette* palette = NULL); /** Sets the depth member (does not affect the bitmap data). @param depth - Bitmap depth. + Bitmap depth. */ void SetDepth(int depth); @@ -587,7 +669,7 @@ public: Sets the height member (does not affect the bitmap data). @param height - Bitmap height in pixels. + Bitmap height in pixels. */ void SetHeight(int height); @@ -596,7 +678,7 @@ public: @remarks The bitmap object owns the mask once this has been called. - @sa GetMask(), wxMask + @see GetMask(), wxMask */ void SetMask(wxMask* mask); @@ -604,9 +686,9 @@ public: Sets the associated palette. (Not implemented under GTK+). @param palette - The palette to set. + The palette to set. - @sa wxPalette + @see wxPalette */ void SetPalette(const wxPalette& palette); @@ -614,7 +696,7 @@ public: Sets the width member (does not affect the bitmap data). @param width - Bitmap width in pixels. + Bitmap width in pixels. */ void SetWidth(int width); @@ -622,7 +704,7 @@ public: Assignment operator, using @ref overview_trefcount "reference counting". @param bitmap - Bitmap to assign. + Bitmap to assign. */ wxBitmap operator =(const wxBitmap& bitmap); }; @@ -655,13 +737,11 @@ public: yet implemented for GTK. @param bitmap - A valid bitmap. - + A valid bitmap. @param colour - A colour specifying the transparency RGB values. - + A colour specifying the transparency RGB values. @param index - Index into a palette, specifying the transparency colour. + Index into a palette, specifying the transparency colour. */ wxMask(); wxMask(const wxBitmap& bitmap); @@ -682,13 +762,11 @@ public: yet implemented for GTK. @param bitmap - A valid bitmap. - + A valid bitmap. @param colour - A colour specifying the transparency RGB values. - + A colour specifying the transparency RGB values. @param index - Index into a palette, specifying the transparency colour. + Index into a palette, specifying the transparency colour. */ bool Create(const wxBitmap& bitmap); bool Create(const wxBitmap& bitmap, const wxColour& colour); diff --git a/interface/bmpbuttn.h b/interface/bmpbuttn.h index 783cb848de..d9edb69739 100644 --- a/interface/bmpbuttn.h +++ b/interface/bmpbuttn.h @@ -31,7 +31,7 @@ @endStyleTable @beginEventTable - @event{EVT_BUTTON(id\, func)}: + @event{EVT_BUTTON(id, func)}: Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked. @endEventTable @@ -51,39 +51,32 @@ public: Constructor, creating and showing a button. @param parent - Parent window. Must not be @NULL. - + Parent window. Must not be @NULL. @param id - Button identifier. The value wxID_ANY indicates a default value. - + Button identifier. The value wxID_ANY indicates a default value. @param bitmap - Bitmap to be displayed. - + Bitmap to be displayed. @param pos - Button position. - + Button position. @param size - Button size. If wxDefaultSize is specified then the button is sized - appropriately for the bitmap. - + Button size. If wxDefaultSize is specified then the button is + sized + appropriately for the bitmap. @param style - Window style. See wxBitmapButton. - + Window style. See wxBitmapButton. @param validator - Window validator. - + Window validator. @param name - Window name. + Window name. @remarks The bitmap parameter is normally the only bitmap you need to - provide, and wxWidgets will draw the button correctly - in its different states. If you want more control, - call any of the functions - SetBitmapSelected(), - SetBitmapFocus(), - SetBitmapDisabled(). - - @sa Create(), wxValidator + provide, and wxWidgets will draw the button correctly + in its different states. If you want more control, call + any of the functions SetBitmapSelected(), + SetBitmapFocus(), + SetBitmapDisabled(). + + @see Create(), wxValidator */ wxBitmapButton(); wxBitmapButton(wxWindow* parent, wxWindowID id, @@ -118,7 +111,7 @@ public: @returns A reference to the disabled state bitmap. - @sa SetBitmapDisabled() + @see SetBitmapDisabled() */ const wxBitmap GetBitmapDisabled(); wxBitmap GetBitmapDisabled(); @@ -130,7 +123,7 @@ public: @returns A reference to the focused state bitmap. - @sa SetBitmapFocus() + @see SetBitmapFocus() */ const wxBitmap GetBitmapFocus(); wxBitmap GetBitmapFocus(); @@ -140,7 +133,7 @@ public: /** Returns the bitmap used when the mouse is over the button, may be invalid. - @sa SetBitmapHover() + @see SetBitmapHover() */ const wxBitmap GetBitmapHover(); wxBitmap GetBitmapHover(); @@ -152,7 +145,7 @@ public: @returns A reference to the button's label bitmap. - @sa SetBitmapLabel() + @see SetBitmapLabel() */ const wxBitmap GetBitmapLabel(); wxBitmap GetBitmapLabel(); @@ -163,7 +156,7 @@ public: @returns A reference to the selected state bitmap. - @sa SetBitmapSelected() + @see SetBitmapSelected() */ wxBitmap GetBitmapSelected(); @@ -171,10 +164,10 @@ public: Sets the bitmap for the disabled button appearance. @param bitmap - The bitmap to set. + The bitmap to set. - @sa GetBitmapDisabled(), SetBitmapLabel(), - SetBitmapSelected(), SetBitmapFocus() + @see GetBitmapDisabled(), SetBitmapLabel(), + SetBitmapSelected(), SetBitmapFocus() */ void SetBitmapDisabled(const wxBitmap& bitmap); @@ -182,20 +175,19 @@ public: Sets the bitmap for the button appearance when it has the keyboard focus. @param bitmap - The bitmap to set. + The bitmap to set. - @sa GetBitmapFocus(), SetBitmapLabel(), - SetBitmapSelected(), SetBitmapDisabled() + @see GetBitmapFocus(), SetBitmapLabel(), + SetBitmapSelected(), SetBitmapDisabled() */ void SetBitmapFocus(const wxBitmap& bitmap); /** Sets the bitmap to be shown when the mouse is over the button. - This function is new since wxWidgets version 2.7.0 and the hover bitmap is currently only supported in wxMSW. - @sa GetBitmapHover() + @see GetBitmapHover() */ void SetBitmapHover(const wxBitmap& bitmap); @@ -203,12 +195,12 @@ public: Sets the bitmap label for the button. @param bitmap - The bitmap label to set. + The bitmap label to set. @remarks This is the bitmap used for the unselected state, and for all - other states if no other bitmaps are provided. + other states if no other bitmaps are provided. - @sa GetBitmapLabel() + @see GetBitmapLabel() */ void SetBitmapLabel(const wxBitmap& bitmap); @@ -216,7 +208,7 @@ public: Sets the bitmap for the selected (depressed) button appearance. @param bitmap - The bitmap to set. + The bitmap to set. */ void SetBitmapSelected(const wxBitmap& bitmap); }; diff --git a/interface/bmpcbox.h b/interface/bmpcbox.h index b94caff3ec..5d8e53ba26 100644 --- a/interface/bmpcbox.h +++ b/interface/bmpcbox.h @@ -28,13 +28,13 @@ @endStyleTable @beginEventTable - @event{EVT_COMBOBOX(id\, func)}: + @event{EVT_COMBOBOX(id, func)}: Process a wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on the list is selected. - @event{EVT_TEXT(id\, func)}: + @event{EVT_TEXT(id, func)}: Process a wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text changes. - @event{EVT_TEXT_ENTER(id\, func)}: + @event{EVT_TEXT_ENTER(id, func)}: Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in the combobox. @endEventTable @@ -54,37 +54,29 @@ public: Constructor, creating and showing a combobox. @param parent - Parent window. Must not be @NULL. - + Parent window. Must not be @NULL. @param id - Window identifier. The value wxID_ANY indicates a default value. - + Window identifier. The value wxID_ANY indicates a default value. @param value - Initial selection string. An empty string indicates no selection. - + Initial selection string. An empty string indicates no selection. @param pos - Window position. - + Window position. @param size - Window size. If wxDefaultSize is specified then the window is sized - appropriately. - + Window size. If wxDefaultSize is specified then the window is + sized + appropriately. @param n - Number of strings with which to initialise the control. - + Number of strings with which to initialise the control. @param choices - An array of strings with which to initialise the control. - + An array of strings with which to initialise the control. @param style - Window style. See wxBitmapComboBox. - + Window style. See wxBitmapComboBox. @param validator - Window validator. - + Window validator. @param name - Window name. + Window name. - @sa Create(), wxValidator + @see Create(), wxValidator */ wxBitmapComboBox(); wxBitmapComboBox(wxWindow* parent, wxWindowID id, @@ -92,7 +84,7 @@ public: const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, int n = 0, - const wxString choices[] = @NULL, + const wxString choices[] = NULL, long style = 0, const wxValidator& validator = wxDefaultValidator, const wxString& name = "comboBox"); @@ -119,9 +111,9 @@ public: int Append(const wxString& item, const wxBitmap& bitmap = wxNullBitmap); int Append(const wxString& item, const wxBitmap& bitmap, - void * clientData); + void* clientData); int Append(const wxString& item, const wxBitmap& bitmap, - wxClientData * clientData); + wxClientData* clientData); //@} //@{ @@ -168,10 +160,10 @@ public: unsigned int pos); int Insert(const wxString& item, const wxBitmap& bitmap, unsigned int pos, - void * clientData); + void* clientData); int Insert(const wxString& item, const wxBitmap& bitmap, unsigned int pos, - wxClientData * clientData); + wxClientData* clientData); //@} /** diff --git a/interface/brush.h b/interface/brush.h index f4752aa3e7..b94094f5ba 100644 --- a/interface/brush.h +++ b/interface/brush.h @@ -52,69 +52,120 @@ public: Copy constructor, uses @ref overview_trefcount "reference counting". @param colour - Colour object. - + Colour object. @param colourName - Colour name. The name will be looked up in the colour database. - + Colour name. The name will be looked up in the colour database. @param style - One of: + One of: - wxTRANSPARENT - Transparent (no fill). - wxSOLID - Solid. + wxTRANSPARENT - wxSTIPPLE - Uses a bitmap as a stipple. - wxBDIAGONAL_HATCH + Transparent (no fill). - Backward diagonal hatch. - wxCROSSDIAG_HATCH - Cross-diagonal hatch. + wxSOLID - wxFDIAGONAL_HATCH - Forward diagonal hatch. - wxCROSS_HATCH + Solid. - Cross hatch. - wxHORIZONTAL_HATCH - Horizontal hatch. + wxSTIPPLE - wxVERTICAL_HATCH - Vertical hatch. - @param brush - Pointer or reference to a brush to copy. + Uses a bitmap as a stipple. + + + + + + wxBDIAGONAL_HATCH + + + + + Backward diagonal hatch. + + + + + + wxCROSSDIAG_HATCH + + + + + Cross-diagonal hatch. + + + + + + wxFDIAGONAL_HATCH + + + + Forward diagonal hatch. + + + + + + wxCROSS_HATCH + + + + + Cross hatch. + + + + + + wxHORIZONTAL_HATCH + + + + + Horizontal hatch. + + + + + + wxVERTICAL_HATCH + + + + + Vertical hatch. + @param brush + Pointer or reference to a brush to copy. @param stippleBitmap - A bitmap to use for stippling. + A bitmap to use for stippling. @remarks If a stipple brush is created, the brush style will be set to - wxSTIPPLE. + wxSTIPPLE. - @sa wxBrushList, wxColour, wxColourDatabase + @see wxBrushList, wxColour, wxColourDatabase */ wxBrush(); wxBrush(const wxColour& colour, int style = wxSOLID); @@ -129,18 +180,18 @@ public: more info. @remarks Although all remaining brushes are deleted when the application - exits, the application should try to clean up all - brushes itself. This is because wxWidgets cannot know - if a pointer to the brush object is stored in an - application data structure, and there is a risk of - double deletion. + exits, the application should try to clean up all + brushes itself. This is because wxWidgets cannot know + if a pointer to the brush object is stored in an + application data structure, and there is a risk of + double deletion. */ ~wxBrush(); /** Returns a reference to the brush colour. - @sa SetColour() + @see SetColour() */ wxColour GetColour(); @@ -150,72 +201,61 @@ public: this bitmap may be non-@NULL but uninitialised (@ref wxBitmap::isok wxBitmap:IsOk returns @false). - @sa SetStipple() + @see SetStipple() */ - wxBitmap * GetStipple(); + wxBitmap* GetStipple(); /** Returns the brush style, one of: @b wxTRANSPARENT - Transparent (no fill). @b wxSOLID - Solid. @b wxBDIAGONAL_HATCH - Backward diagonal hatch. @b wxCROSSDIAG_HATCH - Cross-diagonal hatch. @b wxFDIAGONAL_HATCH - Forward diagonal hatch. @b wxCROSS_HATCH - Cross hatch. @b wxHORIZONTAL_HATCH - Horizontal hatch. @b wxVERTICAL_HATCH - Vertical hatch. @b wxSTIPPLE - Stippled using a bitmap. @b wxSTIPPLE_MASK_OPAQUE - Stippled using a bitmap's mask. - - @sa SetStyle(), SetColour(), SetStipple() + @see SetStyle(), SetColour(), SetStipple() */ int GetStyle(); /** Returns @true if the style of the brush is any of hatched fills. - @sa GetStyle() + @see GetStyle() */ bool IsHatch(); @@ -224,13 +264,13 @@ public: constructor has been used (for example, the brush is a member of a class, or @NULL has been assigned to it). */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); //@{ /** Sets the brush colour using red, green and blue values. - @sa GetColour() + @see GetColour() */ void SetColour(wxColour& colour); void SetColour(const wxString& colourName); @@ -242,13 +282,13 @@ public: Sets the stipple bitmap. @param bitmap - The bitmap to use for stippling. + The bitmap to use for stippling. @remarks The style will be set to wxSTIPPLE, unless the bitmap has a mask - associated to it, in which case the style will be set - to wxSTIPPLE_MASK_OPAQUE. + associated to it, in which case the style will be set + to wxSTIPPLE_MASK_OPAQUE. - @sa wxBitmap + @see wxBitmap */ void SetStipple(const wxBitmap& bitmap); @@ -256,59 +296,120 @@ public: Sets the brush style. @param style - One of: + One of: - wxTRANSPARENT - Transparent (no fill). - wxSOLID - Solid. + wxTRANSPARENT - wxBDIAGONAL_HATCH - Backward diagonal hatch. - wxCROSSDIAG_HATCH + Transparent (no fill). - Cross-diagonal hatch. - wxFDIAGONAL_HATCH - Forward diagonal hatch. + wxSOLID - wxCROSS_HATCH - Cross hatch. - wxHORIZONTAL_HATCH + Solid. - Horizontal hatch. - wxVERTICAL_HATCH - Vertical hatch. + wxBDIAGONAL_HATCH - wxSTIPPLE - Stippled using a bitmap. - wxSTIPPLE_MASK_OPAQUE + Backward diagonal hatch. - Stippled using a bitmap's mask. - @sa GetStyle() + + + wxCROSSDIAG_HATCH + + + + + Cross-diagonal hatch. + + + + + + wxFDIAGONAL_HATCH + + + + + Forward diagonal hatch. + + + + + + wxCROSS_HATCH + + + + + Cross hatch. + + + + + + wxHORIZONTAL_HATCH + + + + + Horizontal hatch. + + + + + + wxVERTICAL_HATCH + + + + + Vertical hatch. + + + + + + wxSTIPPLE + + + + + Stippled using a bitmap. + + + + + + wxSTIPPLE_MASK_OPAQUE + + + + + Stippled using a bitmap's mask. + + @see GetStyle() */ void SetStyle(int style); diff --git a/interface/buffer.h b/interface/buffer.h index e5092f67cc..c29919daf0 100644 --- a/interface/buffer.h +++ b/interface/buffer.h @@ -27,7 +27,7 @@ public: Create a new buffer. @param size - size of new buffer. + size of new buffer. */ wxMemoryBuffer(const wxMemoryBuffer& src); wxMemoryBuffer(size_t size); @@ -37,7 +37,7 @@ public: Append a single byte to the buffer. @param data - New byte to append to the buffer. + New byte to append to the buffer. */ void AppendByte(char data); @@ -48,10 +48,10 @@ public: the existing data. @param sizeNeeded - Amount of extra space required in the buffer for - the append operation + Amount of extra space required in the buffer for + the append operation */ - void * GetAppendBuf(size_t sizeNeeded); + void* GetAppendBuf(size_t sizeNeeded); /** Returns the size of the buffer. @@ -71,12 +71,12 @@ public: /** Ensure the buffer is big enough and return a pointer to the buffer which can be used to directly write into the buffer - up to @e sizeNeeded bytes. + up to @a sizeNeeded bytes. */ - void * GetWriteBuf(size_t sizeNeeded); + void* GetWriteBuf(size_t sizeNeeded); /** - Ensures the buffer has at least @e size bytes available. + Ensures the buffer has at least @a size bytes available. */ void SetBufSize(size_t size); @@ -85,8 +85,8 @@ public: existing data. @param size - New length of the valid data in the buffer. This is - distinct from the allocated size + New length of the valid data in the buffer. This is + distinct from the allocated size */ void SetDataLen(size_t size); @@ -95,8 +95,8 @@ public: you must have used GetAppendBuf() to initialise. @param sizeUsed - This is the amount of new data that has been - appended. + This is the amount of new data that has been + appended. */ void UngetAppendBuf(size_t sizeUsed); @@ -105,8 +105,8 @@ public: you must have used GetWriteBuf() to initialise. @param sizeUsed - The amount of data written in to buffer - by the direct write + The amount of data written in to buffer + by the direct write */ void UngetWriteBuf(size_t sizeUsed); }; diff --git a/interface/busyinfo.h b/interface/busyinfo.h index 450a1e9d5b..cc68c8c65e 100644 --- a/interface/busyinfo.h +++ b/interface/busyinfo.h @@ -58,13 +58,12 @@ class wxBusyInfo { public: /** - Constructs a busy info window as child of @e parent and displays @e msg + Constructs a busy info window as child of @a parent and displays @e msg in it. - - @b NB: If @e parent is not @NULL you must ensure that it is not + @b NB: If @a parent is not @NULL you must ensure that it is not closed while the busy info is shown. */ - wxBusyInfo(const wxString& msg, wxWindow* parent = @NULL); + wxBusyInfo(const wxString& msg, wxWindow* parent = NULL); /** Hides and closes the window containing the information text. diff --git a/interface/button.h b/interface/button.h index 78619a6c45..3db1b2dcc3 100644 --- a/interface/button.h +++ b/interface/button.h @@ -32,7 +32,7 @@ @endStyleTable @beginEventTable - @event{EVT_BUTTON(id\, func)}: + @event{EVT_BUTTON(id, func)}: Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked. @endEventTable @@ -50,39 +50,31 @@ public: //@{ /** Constructor, creating and showing a button. - The preferred way to create standard buttons is to use default value of - @e label. If no label is supplied and @e id is one of standard IDs from + @e label. If no label is supplied and @a id is one of standard IDs from @ref overview_stockitems "this list", standard label will be used. In addition to that, the button will be decorated with stock icons under GTK+ 2. @param parent - Parent window. Must not be @NULL. - + Parent window. Must not be @NULL. @param id - Button identifier. A value of wxID_ANY indicates a default value. - + Button identifier. A value of wxID_ANY indicates a default value. @param label - Text to be displayed on the button. - + Text to be displayed on the button. @param pos - Button position. - + Button position. @param size - Button size. If the default size is specified then the button is sized - appropriately for the text. - + Button size. If the default size is specified then the button is sized + appropriately for the text. @param style - Window style. See wxButton. - + Window style. See wxButton. @param validator - Window validator. - + Window validator. @param name - Window name. + Window name. - @sa Create(), wxValidator + @see Create(), wxValidator */ wxButton(); wxButton(wxWindow* parent, wxWindowID id, @@ -123,7 +115,7 @@ public: @returns The button's label. - @sa SetLabel() + @see SetLabel() */ wxString GetLabel(); @@ -132,11 +124,11 @@ public: box. @remarks Under Windows, only dialog box buttons respond to this function. - As normal under Windows and Motif, pressing return - causes the default button to be depressed when the - return key is pressed. See also wxWindow::SetFocus - which sets the keyboard focus for windows and text - panel items, and wxTopLevelWindow::SetDefaultItem. + As normal under Windows and Motif, pressing return + causes the default button to be depressed when the + return key is pressed. See also wxWindow::SetFocus + which sets the keyboard focus for windows and text + panel items, and wxTopLevelWindow::SetDefaultItem. */ void SetDefault(); @@ -144,7 +136,7 @@ public: Sets the string label for the button. @param label - The label to set. + The label to set. */ void SetLabel(const wxString& label); }; diff --git a/interface/calctrl.h b/interface/calctrl.h index a374ab5f6f..f9787d92db 100644 --- a/interface/calctrl.h +++ b/interface/calctrl.h @@ -249,7 +249,7 @@ public: style bit directly. It enables or disables the special highlighting of the holidays. */ - void EnableHolidayDisplay(bool display = @true); + void EnableHolidayDisplay(bool display = true); /** This function should be used instead of changing @@ -257,21 +257,20 @@ public: change the month interactively. Note that if the month can not be changed, the year can not be changed neither. */ - void EnableMonthChange(bool enable = @true); + void EnableMonthChange(bool enable = true); /** This function should be used instead of changing @c wxCAL_NO_YEAR_CHANGE style bit directly. It allows or disallows the user to change the year interactively. */ - void EnableYearChange(bool enable = @true); + void EnableYearChange(bool enable = true); /** Returns the attribute for the given date (should be in the range 1...31). - The returned pointer may be @NULL. */ - wxCalendarDateAttr * GetAttr(size_t day); + wxCalendarDateAttr* GetAttr(size_t day); /** Gets the currently selected date. @@ -281,53 +280,53 @@ public: /** Gets the background colour of the header part of the calendar window. - @sa SetHeaderColours() + @see SetHeaderColours() */ const wxColour GetHeaderColourBg(); /** Gets the foreground colour of the header part of the calendar window. - @sa SetHeaderColours() + @see SetHeaderColours() */ const wxColour GetHeaderColourFg(); /** Gets the background highlight colour. - @sa SetHighlightColours() + @see SetHighlightColours() */ const wxColour GetHighlightColourBg(); /** Gets the foreground highlight colour. - @sa SetHighlightColours() + @see SetHighlightColours() */ const wxColour GetHighlightColourFg(); /** Return the background colour currently used for holiday highlighting. - @sa SetHolidayColours() + @see SetHolidayColours() */ const wxColour GetHolidayColourBg(); /** Return the foreground colour currently used for holiday highlighting. - @sa SetHolidayColours() + @see SetHolidayColours() */ const wxColour GetHolidayColourFg(); /** Returns one of @c wxCAL_HITTEST_XXX - constants and fills either @e date or - @e wd pointer with the corresponding value depending on the hit test code. + constants and fills either @a date or + @a wd pointer with the corresponding value depending on the hit test code. */ wxCalendarHitTestResult HitTest(const wxPoint& pos, - wxDateTime* date = @NULL, - wxDateTime::WeekDay* wd = @NULL); + wxDateTime* date = NULL, + wxDateTime::WeekDay* wd = NULL); /** Clears any attributes associated with the given day (in the range @@ -337,7 +336,6 @@ public: /** Associates the attribute with the specified date (in the range 1...31). - If the pointer is @NULL, the items attribute is cleared. */ void SetAttr(size_t day, wxCalendarDateAttr* attr); diff --git a/interface/caret.h b/interface/caret.h index 2a12a4f258..4e8a9c177d 100644 --- a/interface/caret.h +++ b/interface/caret.h @@ -60,16 +60,12 @@ public: /** Get the caret position (in pixels). - - @b GetPosition() - Returns a Wx::Point @b GetPositionXY() - Returns a 2-element list @c ( x, y ) */ @@ -81,16 +77,12 @@ public: /** Get the caret size. - - @b GetSize() - Returns a Wx::Size @b GetSizeWH() - Returns a 2-element list @c ( width, height ) */ @@ -111,7 +103,7 @@ public: /** Returns @true if the caret was created successfully. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** Returns @true if the caret is visible and @false if it is permanently @@ -132,10 +124,10 @@ public: Sets the blink time for all the carets. @remarks Under Windows, this function will change the blink time for all - carets permanently (until the next time it is - called), even for the carets in other applications. + carets permanently (until the next time it is called), + even for the carets in other applications. - @sa GetBlinkTime() + @see GetBlinkTime() */ static void SetBlinkTime(int milliseconds); @@ -151,5 +143,5 @@ public: Shows or hides the caret. Notice that if the caret was hidden N times, it must be shown N times as well to reappear on the screen. */ - void Show(bool show = @true); + void Show(bool show = true); }; diff --git a/interface/chartype.h b/interface/chartype.h index 48c2f65222..6ac118fe37 100644 --- a/interface/chartype.h +++ b/interface/chartype.h @@ -12,7 +12,6 @@ words, @c 'x' or @c "foo") to automatically convert them to Unicode in Unicode build configuration. Please see the @ref overview_unicode "Unicode overview" for more information. - This macro is simply returns the value passed to it without changes in ASCII build. In fact, its definition is: @@ -25,7 +24,7 @@ @endcode */ wxChar wxT(char ch); -const wxChar * wxT(const char * s); +const wxChar* wxT(const char* s); //@} @@ -39,9 +38,9 @@ const wxChar * wxT(const char * s); current build, but using it can be beneficial in performance-sensitive code to do the conversion at compile-time instead. - @sa wxT + @see wxT */ wxStringCharType wxS(char ch); -const wxStringCharType * wxS(const char * s); +const wxStringCharType* wxS(const char* s); //@} diff --git a/interface/checkbox.h b/interface/checkbox.h index 86f9ad3460..09c30ce4fb 100644 --- a/interface/checkbox.h +++ b/interface/checkbox.h @@ -30,7 +30,7 @@ @endStyleTable @beginEventTable - @event{EVT_CHECKBOX(id\, func)}: + @event{EVT_CHECKBOX(id, func)}: Process a wxEVT_COMMAND_CHECKBOX_CLICKED event, when the checkbox is clicked. @endEventTable @@ -50,32 +50,25 @@ public: Constructor, creating and showing a checkbox. @param parent - Parent window. Must not be @NULL. - + Parent window. Must not be @NULL. @param id - Checkbox identifier. The value wxID_ANY indicates a default value. - + Checkbox identifier. The value wxID_ANY indicates a default value. @param label - Text to be displayed next to the checkbox. - + Text to be displayed next to the checkbox. @param pos - Checkbox position. If wxDefaultPosition is specified then a default + Checkbox position. If wxDefaultPosition is specified then a default position is chosen. - @param size - Checkbox size. If wxDefaultSize is specified then a default size is - chosen. - + Checkbox size. If wxDefaultSize is specified then a default + size is chosen. @param style - Window style. See wxCheckBox. - + Window style. See wxCheckBox. @param validator - Window validator. - + Window validator. @param name - Window name. + Window name. - @sa Create(), wxValidator + @see Create(), wxValidator */ wxCheckBox(); wxCheckBox(wxWindow* parent, wxWindowID id, @@ -108,10 +101,10 @@ public: Gets the state of a 3-state checkbox. @returns Returns wxCHK_UNCHECKED when the checkbox is unchecked, - wxCHK_CHECKED when it is checked and - wxCHK_UNDETERMINED when it's in the undetermined - state. Asserts when the function is used with a - 2-state checkbox. + wxCHK_CHECKED when it is checked and + wxCHK_UNDETERMINED when it's in the undetermined state. + Asserts when the function is used with a 2-state + checkbox. */ wxCheckBoxState Get3StateValue(); @@ -126,7 +119,7 @@ public: Returns whether or not the checkbox is a 3-state checkbox. @returns Returns @true if this checkbox is a 3-state checkbox, @false if - it's a 2-state checkbox. + it's a 2-state checkbox. */ bool Is3State(); @@ -134,8 +127,8 @@ public: Returns whether or not the user can set the checkbox to the third state. @returns Returns @true if the user can set the third state of this - checkbox, @false if it can only be set - programmatically or if it's a 2-state checkbox. + checkbox, @false if it can only be set programmatically + or if it's a 2-state checkbox. */ bool Is3rdStateAllowedForUser(); @@ -151,7 +144,7 @@ public: wxEVT_COMMAND_CHECKBOX_CLICKED event to get emitted. @param state - If @true, the check is on, otherwise it is off. + If @true, the check is on, otherwise it is off. */ void SetValue(bool state); }; diff --git a/interface/checklst.h b/interface/checklst.h index 880ab4378c..3fd990b9ec 100644 --- a/interface/checklst.h +++ b/interface/checklst.h @@ -21,7 +21,7 @@ and therefore this is not available to the application. @beginEventTable - @event{EVT_CHECKLISTBOX(id\, func)}: + @event{EVT_CHECKLISTBOX(id, func)}: Process a wxEVT_COMMAND_CHECKLISTBOX_TOGGLED event, when an item in the check list box is checked or unchecked. @endEventTable @@ -41,39 +41,32 @@ public: Constructor, creating and showing a list box. @param parent - Parent window. Must not be @NULL. - + Parent window. Must not be @NULL. @param id - Window identifier. The value wxID_ANY indicates a default value. - + Window identifier. The value wxID_ANY indicates a default value. @param pos - Window position. - + Window position. @param size - Window size. If wxDefaultSize is specified then the window is sized - appropriately. - + Window size. If wxDefaultSize is specified then the window is + sized + appropriately. @param n - Number of strings with which to initialise the control. - + Number of strings with which to initialise the control. @param choices - An array of strings with which to initialise the control. - + An array of strings with which to initialise the control. @param style - Window style. See wxCheckListBox. - + Window style. See wxCheckListBox. @param validator - Window validator. - + Window validator. @param name - Window name. + Window name. */ wxCheckListBox(); wxCheckListBox(wxWindow* parent, wxWindowID id, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, int n, - const wxString choices[] = @NULL, + const wxString choices[] = NULL, long style = 0, const wxValidator& validator = wxDefaultValidator, const wxString& name = "listBox"); @@ -96,10 +89,9 @@ public: wxEVT_COMMAND_CHECKLISTBOX_TOGGLE being emitted. @param item - Index of item to check. - + Index of item to check. @param check - @true if the item is to be checked, @false otherwise. + @true if the item is to be checked, @false otherwise. */ - void Check(int item, bool check = @true); + void Check(int item, bool check = true); }; diff --git a/interface/choicdlg.h b/interface/choicdlg.h index 4f6f99974f..44de9f59ea 100644 --- a/interface/choicdlg.h +++ b/interface/choicdlg.h @@ -28,45 +28,62 @@ public: Constructor taking an array of wxString choices. @param parent - Parent window. - + Parent window. @param message - Message to show on the dialog. - + Message to show on the dialog. @param caption - The dialog caption. - + The dialog caption. @param n - The number of choices. - + The number of choices. @param choices - An array of strings, or a string list, containing the choices. - + An array of strings, or a string list, containing the choices. @param style - A dialog style (bitlist) containing flags chosen from standard - dialog styles and the following: + A dialog style (bitlist) containing flags chosen from standard + dialog styles and the following: + + + + + + + + wxOK + + + + Show an OK button. - wxOK - Show an OK button. - wxCANCEL + wxCANCEL - Show a Cancel button. - wxCENTRE - Centre the message. Not Windows. + Show a Cancel button. - The default value is equivalent to wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER | - wxOK | wxCANCEL | wxCENTRE. + + + + wxCENTRE + + + + + Centre the message. Not Windows. + + + + + + The default value is equivalent to wxDEFAULT_DIALOG_STYLE | + wxRESIZE_BORDER | wxOK | wxCANCEL | wxCENTRE. @param pos - Dialog position. Not Windows. + Dialog position. Not Windows. @remarks Use ShowModal() to show the dialog. */ @@ -124,49 +141,65 @@ public: Constructor, taking an array of wxString choices and optional client data. @param parent - Parent window. - + Parent window. @param message - Message to show on the dialog. - + Message to show on the dialog. @param caption - The dialog caption. - + The dialog caption. @param n - The number of choices. - + The number of choices. @param choices - An array of strings, or a string list, containing the choices. - + An array of strings, or a string list, containing the choices. @param clientData - An array of client data to be associated with the items. - See GetSelectionClientData. - + An array of client data to be associated with the items. + See GetSelectionClientData. @param style - A dialog style (bitlist) containing flags chosen from standard - dialog styles and the following: + A dialog style (bitlist) containing flags chosen from standard + dialog styles and the following: + + + + + + + + wxOK + + + + + Show an OK button. + - wxOK - Show an OK button. + wxCANCEL - wxCANCEL - Show a Cancel button. - wxCENTRE + Show a Cancel button. - Centre the message. Not Windows. - The default value is equivalent to wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER | - wxOK | wxCANCEL | wxCENTRE. + + wxCENTRE + + + + + Centre the message. Not Windows. + + + + + + The default value is equivalent to wxDEFAULT_DIALOG_STYLE | + wxRESIZE_BORDER | wxOK | wxCANCEL | wxCENTRE. @param pos - Dialog position. Not Windows. + Dialog position. Not Windows. @remarks Use ShowModal() to show the dialog. */ @@ -174,14 +207,14 @@ public: const wxString& caption, int n, const wxString* choices, - void** clientData = @NULL, + void** clientData = NULL, long style = wxCHOICEDLG_STYLE, const wxPoint& pos = wxDefaultPosition); wxSingleChoiceDialog(wxWindow* parent, const wxString& message, const wxString& caption, const wxArrayString& choices, - void** clientData = @NULL, + void** clientData = NULL, long style = wxCHOICEDLG_STYLE, const wxPoint& pos = wxDefaultPosition); //@} @@ -225,22 +258,22 @@ public: int wxGetSingleChoiceIndex(const wxString& message, const wxString& caption, const wxArrayString& aChoices, - wxWindow * parent = @NULL, + wxWindow* parent = NULL, int x = -1, int y = -1, - bool centre = @true, - int width=150, - int height=200); + bool centre = true, + int width = 150, + int height = 200); int wxGetSingleChoiceIndex(const wxString& message, const wxString& caption, int n, const wxString& choices[], - wxWindow * parent = @NULL, + wxWindow* parent = NULL, int x = -1, int y = -1, - bool centre = @true, - int width=150, - int height=200); + bool centre = true, + int width = 150, + int height = 200); //@} //@{ @@ -250,33 +283,31 @@ int wxGetSingleChoiceIndex(const wxString& message, string or Cancel to return the empty string. Use wxGetSingleChoiceIndex if empty string is a valid choice and if you want to be able to detect pressing Cancel reliably. - You may pass the list of strings to choose from either using @e choices - which is an array of @e n strings for the listbox or by using a single - @e aChoices parameter of type wxArrayString. - - If @e centre is @true, the message text (which may include new line + which is an array of @a n strings for the listbox or by using a single + @a aChoices parameter of type wxArrayString. + If @a centre is @true, the message text (which may include new line characters) is centred; if @false, the message is left-justified. */ wxString wxGetSingleChoice(const wxString& message, const wxString& caption, const wxArrayString& aChoices, - wxWindow * parent = @NULL, + wxWindow* parent = NULL, int x = -1, int y = -1, - bool centre = @true, - int width=150, - int height=200); + bool centre = true, + int width = 150, + int height = 200); wxString wxGetSingleChoice(const wxString& message, const wxString& caption, int n, const wxString& choices[], - wxWindow * parent = @NULL, + wxWindow* parent = NULL, int x = -1, int y = -1, - bool centre = @true, - int width=150, - int height=200); + bool centre = true, + int width = 150, + int height = 200); //@} //@{ @@ -290,23 +321,23 @@ wxString wxGetSingleChoiceData(const wxString& message, const wxString& caption, const wxArrayString& aChoices, const wxString& client_data[], - wxWindow * parent = @NULL, + wxWindow* parent = NULL, int x = -1, int y = -1, - bool centre = @true, - int width=150, - int height=200); + bool centre = true, + int width = 150, + int height = 200); wxString wxGetSingleChoiceData(const wxString& message, const wxString& caption, int n, const wxString& choices[], const wxString& client_data[], - wxWindow * parent = @NULL, + wxWindow* parent = NULL, int x = -1, int y = -1, - bool centre = @true, - int width=150, - int height=200); + bool centre = true, + int width = 150, + int height = 200); //@} //@{ @@ -316,34 +347,32 @@ wxString wxGetSingleChoiceData(const wxString& message, number of items in the listbox whose indices will be returned in @e selection array. The initial contents of this array will be used to select the items when the dialog is shown. - You may pass the list of strings to choose from either using @e choices - which is an array of @e n strings for the listbox or by using a single - @e aChoices parameter of type wxArrayString. - - If @e centre is @true, the message text (which may include new line + which is an array of @a n strings for the listbox or by using a single + @a aChoices parameter of type wxArrayString. + If @a centre is @true, the message text (which may include new line characters) is centred; if @false, the message is left-justified. */ size_t wxGetMultipleChoices(wxArrayInt& selections, const wxString& message, const wxString& caption, const wxArrayString& aChoices, - wxWindow * parent = @NULL, + wxWindow* parent = NULL, int x = -1, int y = -1, - bool centre = @true, - int width=150, - int height=200); + bool centre = true, + int width = 150, + int height = 200); size_t wxGetMultipleChoices(wxArrayInt& selections, const wxString& message, const wxString& caption, int n, const wxString& choices[], - wxWindow * parent = @NULL, + wxWindow* parent = NULL, int x = -1, int y = -1, - bool centre = @true, - int width=150, - int height=200); + bool centre = true, + int width = 150, + int height = 200); //@} diff --git a/interface/choice.h b/interface/choice.h index a29e74a453..42a813237e 100644 --- a/interface/choice.h +++ b/interface/choice.h @@ -20,7 +20,7 @@ @endStyleTable @beginEventTable - @event{EVT_CHOICE(id\, func)}: + @event{EVT_CHOICE(id, func)}: Process a wxEVT_COMMAND_CHOICE_SELECTED event, when an item on the list is selected. @endEventTable @@ -40,44 +40,37 @@ public: Constructor, creating and showing a choice. @param parent - Parent window. Must not be @NULL. - + Parent window. Must not be @NULL. @param id - Window identifier. The value wxID_ANY indicates a default value. - + Window identifier. The value wxID_ANY indicates a default value. @param pos - Window position. - + Window position. @param size - Window size. If wxDefaultSize is specified then the choice is sized - appropriately. - + Window size. If wxDefaultSize is specified then the choice is + sized + appropriately. @param n - Number of strings with which to initialise the choice control. - + Number of strings with which to initialise the choice control. @param choices - An array of strings with which to initialise the choice control. - + An array of strings with which to initialise the choice control. @param style - Window style. See wxChoice. - + Window style. See wxChoice. @param validator - Window validator. - + Window validator. @param name - Window name. + Window name. - @sa Create(), wxValidator + @see Create(), wxValidator */ wxChoice(); - wxChoice(wxWindow * parent, wxWindowID id, + wxChoice(wxWindow* parent, wxWindowID id, const wxPoint& pos, const wxSize& size, int n, const wxString choices[], long style = 0, const wxValidator& validator = wxDefaultValidator, const wxString& name = "choice"); - wxChoice(wxWindow * parent, wxWindowID id, + wxChoice(wxWindow* parent, wxWindowID id, const wxPoint& pos, const wxSize& size, const wxArrayString& choices, @@ -95,13 +88,13 @@ public: /** Creates the choice for two-step construction. See wxChoice(). */ - bool Create(wxWindow * parent, wxWindowID id, const wxPoint& pos, + bool Create(wxWindow* parent, wxWindowID id, const wxPoint& pos, const wxSize& size, int n, const wxString choices[], long style = 0, const wxValidator& validator = wxDefaultValidator, const wxString& name = "choice"); - bool Create(wxWindow * parent, wxWindowID id, + bool Create(wxWindow* parent, wxWindowID id, const wxPoint& pos, const wxSize& size, const wxArrayString& choices, @@ -114,7 +107,7 @@ public: Gets the number of columns in this choice item. @remarks This is implemented for Motif only and always returns 1 for the - other platforms. + other platforms. */ int GetColumns(); @@ -125,7 +118,6 @@ public: That is, while the dropdown list is shown, it returns the currently selected item in it. When it is not shown, its result is the same as for the other function. - This function is new since wxWidgets version 2.6.2 (before this version wxControlWithItems::GetSelection itself behaved like this). @@ -136,7 +128,7 @@ public: Sets the number of columns in this choice item. @param n - Number of columns. + Number of columns. */ void SetColumns(int n = 1); }; diff --git a/interface/clipboard.h b/interface/clipboard.h index 45889ccb8e..563e2bed1b 100644 --- a/interface/clipboard.h +++ b/interface/clipboard.h @@ -7,9 +7,9 @@ ///////////////////////////////////////////////////////////////////////////// /** -Gets the name of a registered clipboard format, and puts it into the buffer @e +Gets the name of a registered clipboard format, and puts it into the buffer @a formatName which is of maximum -length @e maxCount. @e dataFormat must not specify a predefined clipboard +length @e maxCount. @a dataFormat must not specify a predefined clipboard format. */ bool wxGetClipboardFormatName(int dataFormat, @@ -19,16 +19,13 @@ bool wxGetClipboardFormatName(int dataFormat, /** Gets data from the clipboard. - -@e dataFormat may be one of: - +@a dataFormat may be one of: wxCF_TEXT or wxCF_OEMTEXT: returns a pointer to new memory containing a null-terminated text string. wxCF_BITMAP: returns a new wxBitmap. - The clipboard must have previously been opened for this call to succeed. */ -wxObject * wxGetClipboardData(int dataFormat); +wxObject* wxGetClipboardData(int dataFormat); /** Returns @true if the given data format is available on the clipboard. @@ -65,15 +62,12 @@ bool wxCloseClipboard(); to the clipboard. Each call to this function specifies a known available format; the function returns the format that appears next in the list. - - @e dataFormat specifies a known format. If this parameter is zero, + @a dataFormat specifies a known format. If this parameter is zero, the function returns the first format in the list. - The return value specifies the next known clipboard data format if the - function is successful. It is zero if the @e dataFormat parameter specifies + function is successful. It is zero if the @a dataFormat parameter specifies the last format in the list of available formats, or if the clipboard is not open. - Before it enumerates the formats function, an application must open the clipboard by using the wxOpenClipboard function. diff --git a/interface/clipbrd.h b/interface/clipbrd.h index 12ccece555..5ba025568d 100644 --- a/interface/clipbrd.h +++ b/interface/clipbrd.h @@ -18,8 +18,7 @@ To use the clipboard, you call member functions of the global @b wxTheClipboard object. - See also the @ref overview_wxdataobjectoverview "wxDataObject overview" for - further information. + See also the @ref overview_wxdataobjectoverview for further information. Call wxClipboard::Open to get ownership of the clipboard. If this operation returns @true, you @@ -58,7 +57,7 @@ @category{dnd} @seealso - @ref overview_wxdndoverview "Drag and drop overview", wxDataObject + @ref overview_wxdndoverview, wxDataObject */ class wxClipboard : public wxObject { @@ -76,12 +75,11 @@ public: /** Call this function to add the data object to the clipboard. You may call this function repeatedly after having cleared the clipboard using Clear(). - After this function has been called, the clipboard owns the data, so do not delete the data explicitly. - @sa SetData() + @see SetData() */ bool AddData(wxDataObject* data); @@ -104,7 +102,7 @@ public: bool Flush(); /** - Call this function to fill @e data with data on the clipboard, if available in + Call this function to fill @a data with data on the clipboard, if available in the required format. Returns @true on success. */ @@ -131,10 +129,8 @@ public: /** Call this function to open the clipboard before calling SetData() and GetData(). - Call Close() when you have finished with the clipboard. You should keep the clipboard open for only a very short time. - Returns @true on success. This should be tested (as in the sample shown above). */ bool Open(); @@ -143,12 +139,11 @@ public: Call this function to set the data object to the clipboard. This function will clear all previous contents in the clipboard, so calling it several times does not make any sense. - After this function has been called, the clipboard owns the data, so do not delete the data explicitly. - @sa AddData() + @see AddData() */ bool SetData(wxDataObject* data); @@ -157,7 +152,6 @@ public: CLIPBOARD X11 selection by default. When this function is called with @true argument, all subsequent clipboard operations will use PRIMARY selection until this function is called again with @false. - On the other platforms, there is no PRIMARY selection and so all clipboard operations will fail. This allows to implement the standard X11 handling of the clipboard which consists in copying data to the CLIPBOARD selection only when @@ -166,5 +160,5 @@ public: automatically, without overwriting the normal clipboard contents with the currently selected text on the other platforms. */ - void UsePrimarySelection(bool primary = @true); + void UsePrimarySelection(bool primary = true); }; diff --git a/interface/clrpicker.h b/interface/clrpicker.h index f862096299..1aa9f3b80d 100644 --- a/interface/clrpicker.h +++ b/interface/clrpicker.h @@ -45,7 +45,7 @@ public: Initializes the object and calls Create() with all the parameters. */ - wxColourPickerCtrl(wxWindow * parent, wxWindowID id, + wxColourPickerCtrl(wxWindow* parent, wxWindowID id, const wxColour& colour = wxBLACK, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, @@ -55,33 +55,26 @@ public: /** @param parent - Parent window, must not be non-@NULL. - + Parent window, must not be non-@NULL. @param id - The identifier for the control. - + The identifier for the control. @param colour - The initial colour shown in the control. - + The initial colour shown in the control. @param pos - Initial position. - + Initial position. @param size - Initial size. - + Initial size. @param style - The window style, see wxCRLP_* flags. - + The window style, see wxCRLP_* flags. @param validator - Validator which can be used for additional date checks. - + Validator which can be used for additional date checks. @param name - Control name. + Control name. @returns @true if the control was successfully created or @false if - creation failed. + creation failed. */ - bool Create(wxWindow * parent, wxWindowID id, + bool Create(wxWindow* parent, wxWindowID id, const wxColour& colour = wxBLACK, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, @@ -98,8 +91,8 @@ public: /** Sets the currently selected colour. See wxColour::Set. */ - void SetColour(const wxColour & col); - void SetColour(const wxString & colname); + void SetColour(const wxColour& col); + void SetColour(const wxString& colname); //@} }; @@ -123,7 +116,7 @@ public: /** The constructor is not normally used by the user code. */ - wxColourPickerEvent(wxObject * generator, int id, + wxColourPickerEvent(wxObject* generator, int id, const wxColour& colour); /** @@ -134,5 +127,5 @@ public: /** Set the colour associated with the event. */ - void SetColour(const wxColour & pos); + void SetColour(const wxColour& pos); }; diff --git a/interface/cmdline.h b/interface/cmdline.h index e5ab88761e..73754835d8 100644 --- a/interface/cmdline.h +++ b/interface/cmdline.h @@ -82,13 +82,12 @@ public: /** Frees resources allocated by the object. - @b NB: destructor is not virtual, don't use this class polymorphically. */ ~wxCmdLineParser(); /** - Add an option @e name with an optional long name @e lng (no long name if + Add an option @a name with an optional long name @a lng (no long name if it is empty, which is default) taking a value of the given type (string by default) to the command line description. */ @@ -99,15 +98,15 @@ public: int flags = 0); /** - Add a parameter of the given @e type to the command line description. + Add a parameter of the given @a type to the command line description. */ void AddParam(const wxString& desc = wxEmptyString, wxCmdLineParamType type = wxCMD_LINE_VAL_STRING, int flags = 0); /** - Add a switch @e name with an optional long name @e lng (no long name if it - is empty, which is default), description @e desc and flags @e flags to the + Add a switch @a name with an optional long name @a lng (no long name if it + is empty, which is default), description @a desc and flags @a flags to the command line description. */ void AddSwitch(const wxString& name, @@ -118,7 +117,7 @@ public: /** Returns @true if long options are enabled, otherwise @false. - @sa EnableLongOptions() + @see EnableLongOptions() */ bool AreLongOptionsEnabled(); @@ -127,17 +126,14 @@ public: parser object must have the command line to parse and also the rules saying which switches, options and parameters are valid - this is called command line description in what follows. - You have complete freedom of choice as to when specify the required information, the only restriction is that it must be done before calling Parse(). - To specify the command line to parse you may use either one of constructors accepting it (@c wxCmdLineParser(argc, argv) or @c wxCmdLineParser(const wxString) usually) or, if you use the default constructor, you can do it later by calling SetCmdLine(). - The same holds for command line description: it can be specified either in the @ref wxcmdlineparserctor() constructor (with or without the command line itself) or constructed later using either @@ -145,7 +141,6 @@ public: AddSwitch(), AddOption() and AddParam() methods. - Using constructors or SetDesc() uses a (usually @c const static) table containing the command line description. If you want to decide which options to accept during the run-time, using one of the @@ -164,21 +159,18 @@ public: wxCmdLineParser has several global options which may be changed by the application. All of the functions described in this section should be called before Parse(). - First global option is the support for long (also known as GNU-style) options. The long options are the ones which start with two dashes (@c "--") and look like this: @c --verbose, i.e. they generally are complete words and not some abbreviations of them. As long options are used by more and more applications, they are enabled by default, but may be disabled with DisableLongOptions(). - Another global option is the set of characters which may be used to start an option (otherwise, the word on the command line is assumed to be a parameter). Under Unix, @c '-' is always used, but Windows has at least two common choices for this: @c '-' and @c '/'. Some programs also use @c '+'. The default is to use what suits most the current platform, but may be changed with SetSwitchChars() method. - Finally, SetLogo() can be used to show some application-specific text before the explanation given by Usage() function. @@ -192,13 +184,12 @@ public: /** Enable or disable support for the long options. - As long options are not (yet) POSIX-compliant, this option allows to disable them. - @sa Customization() and AreLongOptionsEnabled() + @see Customization() and AreLongOptionsEnabled() */ - void EnableLongOptions(bool enable = @true); + void EnableLongOptions(bool enable = true); //@{ /** @@ -226,7 +217,6 @@ public: After calling Parse() (and if it returned 0), you may access the results of parsing using one of overloaded @c Found() methods. - For a simple switch, you will simply call Found() to determine if the switch was given or not, for an option or a parameter, you will call a version of @c Found() @@ -242,13 +232,13 @@ public: syntax error occurred. @param giveUsage - If @true (default), the usage message is given if a - syntax error was encountered while parsing the command line or if help was - requested. If @false, only error messages about possible syntax errors - are given, use Usage to show the usage message - from the caller if needed. + If @true (default), the usage message is given if a + syntax error was encountered while parsing the command line or if help was + requested. If @false, only error messages about possible syntax errors + are given, use Usage to show the usage message + from the caller if needed. */ - int Parse(bool giveUsage = @true); + int Parse(bool giveUsage = true); /** After the command line description was constructed and the desired options were @@ -257,7 +247,6 @@ public: option was specified (this is a separate case as, normally, the program will terminate after this) or a positive number if there was an error during the command line parsing. - In the latter case, the appropriate error message and usage information are logged by wxCmdLineParser itself using the standard wxWidgets logging functions. */ @@ -274,21 +263,19 @@ public: /** Construct the command line description - Take the command line description from the wxCMD_LINE_NONE terminated table. - Example of usage: */ void SetDesc(const wxCmdLineEntryDesc* desc); /** - @e logo is some extra text which will be shown by + @a logo is some extra text which will be shown by Usage() method. */ void SetLogo(const wxString& logo); /** - @e switchChars contains all characters with which an option or switch may + @a switchChars contains all characters with which an option or switch may start. Default is @c "-" for Unix, @c "-/" for Windows. */ void SetSwitchChars(const wxString& switchChars); @@ -298,7 +285,7 @@ public: options and parameters descriptions specified earlier, so the resulting message will not be helpful to the user unless the descriptions were indeed specified. - @sa SetLogo() + @see SetLogo() */ void Usage(); }; diff --git a/interface/cmdproc.h b/interface/cmdproc.h index 4807c006c7..89cd956dfd 100644 --- a/interface/cmdproc.h +++ b/interface/cmdproc.h @@ -27,16 +27,14 @@ public: /** Constructor. wxCommand is an abstract class, so you will need to derive a new class and call this constructor from your own constructor. - - @e canUndo tells the command processor whether this command is undo-able. You + @a canUndo tells the command processor whether this command is undo-able. You can achieve the same functionality by overriding the CanUndo member function (if for example the criteria for undoability is context-dependent). - - @e name must be supplied for the command processor to display the command name + @a name must be supplied for the command processor to display the command name in the application's edit menu. */ - wxCommand(bool canUndo = @false, const wxString& name = @NULL); + wxCommand(bool canUndo = false, const wxString& name = NULL); /** Destructor. @@ -54,7 +52,7 @@ public: Returning @false will indicate to the command processor that the action is not undoable and should not be added to the command history. */ -#define bool Do() /* implementation is private */ + bool Do(); /** Returns the command name. @@ -66,10 +64,8 @@ public: Return @true to indicate that the action has taken place, @false otherwise. Returning @false will indicate to the command processor that the action is not redoable and no change should be made to the command history. - How you implement this command is totally application dependent, but typical strategies include: - Perform an inverse operation on the last modified piece of data in the document. When redone, a copy of data stored in command is pasted back or some operation reapplied. This relies on the fact that @@ -78,7 +74,6 @@ public: Restore the entire document state (perhaps using document transactioning). Potentially very inefficient, but possibly easier to code if the user interface and data are complex, and an 'inverse execute' operation is hard to write. - The docview sample uses the first method, to remove or restore segments in the drawing. */ @@ -106,8 +101,7 @@ class wxCommandProcessor : public wxObject public: /** Constructor. - - @e maxCommands may be set to a positive integer to limit the number of + @a maxCommands may be set to a positive integer to limit the number of commands stored to it, otherwise (and by default) the list of commands can grow arbitrarily. */ @@ -222,11 +216,10 @@ public: appropriately. If it fails, the command is deleted immediately. Once Submit has been called, the passed command should not be deleted directly by the application. - - @e storeIt indicates whether the successful command should be stored + @a storeIt indicates whether the successful command should be stored in the history list. */ - virtual bool Submit(wxCommand * command, bool storeIt = @true); + virtual bool Submit(wxCommand* command, bool storeIt = true); /** Undoes the command just executed. diff --git a/interface/cmndata.h b/interface/cmndata.h index d66c98d967..e50d18864a 100644 --- a/interface/cmndata.h +++ b/interface/cmndata.h @@ -34,7 +34,6 @@ public: Enables or disables 'effects' under MS Windows or generic only. This refers to the controls for manipulating colour, strikeout and underline properties. - The default value is @true. */ void EnableEffects(bool enable); @@ -43,7 +42,6 @@ public: Under MS Windows, returns a flag determining whether symbol fonts can be selected. Has no effect on other platforms. - The default value is @true. */ bool GetAllowSymbols(); @@ -56,7 +54,6 @@ public: /** Gets the colour associated with the font dialog. - The default value is black. */ wxColour GetColour(); @@ -64,7 +61,6 @@ public: /** Determines whether 'effects' are enabled under Windows. This refers to the controls for manipulating colour, strikeout and underline properties. - The default value is @true. */ bool GetEnableEffects(); @@ -77,7 +73,6 @@ public: /** Returns @true if the Help button will be shown (Windows only). - The default value is @false. */ bool GetShowHelp(); @@ -85,7 +80,6 @@ public: /** Under MS Windows, determines whether symbol fonts can be selected. Has no effect on other platforms. - The default value is @true. */ void SetAllowSymbols(bool allowSymbols); @@ -97,7 +91,6 @@ public: /** Sets the colour that will be used for the font foreground colour. - The default colour is black. */ void SetColour(const wxColour& colour); @@ -109,7 +102,6 @@ public: /** Sets the valid range for the font point size (Windows only). - The default is 0, 0 (unrestricted range). */ void SetRange(int min, int max); @@ -117,7 +109,6 @@ public: /** Determines whether the Help button will be displayed in the font dialog (Windows only). - The default value is @false. */ void SetShowHelp(bool showHelp); @@ -252,7 +243,6 @@ public: /** Returns the paper id (stored in the internal wxPrintData object). - For further information, see wxPrintData::SetPaperId. */ wxPaperSize GetPaperId(); @@ -273,7 +263,7 @@ public: This can return @false on Windows if the current printer is not set, for example. On all other platforms, it returns @true. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** Pass @true if the dialog will simply return default printer information (such as @@ -315,7 +305,6 @@ public: /** Sets the paper size id. For further information, see wxPrintData::SetPaperId. - Calling this function overrides the explicit paper dimensions passed in SetPaperSize(). */ @@ -378,22 +367,19 @@ public: dialog will display full rgb colour picker or only available palette indexer. Has no meaning under other platforms. - The default value is @true. */ bool GetChooseFull(); /** Gets the current colour associated with the colour dialog. - The default colour is black. */ wxColour GetColour(); /** - Gets the @e ith custom colour associated with the colour dialog. @e i should + Gets the @e ith custom colour associated with the colour dialog. @a i should be an integer between 0 and 15. - The default custom colours are invalid colours. */ wxColour GetCustomColour(int i); @@ -401,22 +387,19 @@ public: /** Under Windows, tells the Windows colour dialog to display the full dialog with custom colour selection controls. Under other platforms, has no effect. - The default value is @true. */ void SetChooseFull(const bool flag); /** Sets the default colour for the colour dialog. - The default colour is black. */ void SetColour(const wxColour& colour); /** - Sets the @e ith custom colour for the colour dialog. @e i should + Sets the @e ith custom colour for the colour dialog. @a i should be an integer between 0 and 15. - The default custom colours are invalid colours. */ void SetCustomColour(int i, const wxColour& colour); @@ -464,7 +447,6 @@ public: /** Returns the current bin (papersource). By default, the system is left to select the bin (@c wxPRINTBIN_DEFAULT is returned). - See SetBin() for the full list of bin values. */ wxPrintBin GetBin(); @@ -511,6 +493,7 @@ public: Returns the current print quality. This can be a positive integer, denoting the number of dots per inch, or one of the following identifiers: + On input you should pass one of these identifiers, but on return you may get back a positive integer indicating the current resolution setting. @@ -522,7 +505,7 @@ public: This can return @false on Windows if the current printer is not set, for example. On all other platforms, it returns @true. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** Sets the current bin. Possible values are: @@ -560,8 +543,7 @@ public: between paper id, paper size and string name, see wxPrintPaperDatabase in @c paper.h (not yet documented). - - @e paperId can be one of: + @a paperId can be one of: */ void SetPaperId(wxPaperSize paperId); @@ -575,6 +557,7 @@ public: Sets the desired print quality. This can be a positive integer, denoting the number of dots per inch, or one of the following identifiers: + On input you should pass one of these identifiers, but on return you may get back a positive integer indicating the current resolution setting. @@ -701,7 +684,7 @@ public: This can return @false on Windows if the current printer is not set, for example. On all other platforms, it returns @true. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** Sets the 'Collate' checkbox to @true or @false. @@ -748,7 +731,6 @@ public: /** Determines whether the dialog to be shown will be the Print dialog (pass @false) or Print Setup dialog (pass @true). - This function has been deprecated since version 2.5.4. */ void SetSetupDialog(bool flag); diff --git a/interface/collpane.h b/interface/collpane.h index 123a9c0cd8..fba09358f5 100644 --- a/interface/collpane.h +++ b/interface/collpane.h @@ -25,7 +25,7 @@ public: /** The constructor is not normally used by the user code. */ - wxCollapsiblePaneEvent(wxObject * generator, int id, + wxCollapsiblePaneEvent(wxObject* generator, int id, bool collapsed); /** @@ -34,9 +34,9 @@ public: bool GetCollapsed(); /** - Sets this as a collapsed pane event (if @e collapsed is @true) or as an + Sets this as a collapsed pane event (if @a collapsed is @true) or as an expanded - pane event (if @e collapsed is @false). + pane event (if @a collapsed is @false). */ void SetCollapsed(bool collapsed); }; @@ -106,7 +106,7 @@ public: Initializes the object and calls Create() with all the parameters. */ - wxCollapsiblePane(wxWindow * parent, wxWindowID id, + wxCollapsiblePane(wxWindow* parent, wxWindowID id, const wxString& label, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, @@ -117,38 +117,31 @@ public: /** Collapses or expands the pane window. */ - void Collapse(bool collapse = @true); + void Collapse(bool collapse = true); /** @param parent - Parent window, must not be non-@NULL. - + Parent window, must not be non-@NULL. @param id - The identifier for the control. - + The identifier for the control. @param label - The initial label shown in the button which allows the user to expand or + The initial label shown in the button which allows the user to expand or collapse the pane window. - @param pos - Initial position. - + Initial position. @param size - Initial size. - + Initial size. @param style - The window style, see wxCP_* flags. - + The window style, see wxCP_* flags. @param validator - Validator which can be used for additional date checks. - + Validator which can be used for additional date checks. @param name - Control name. + Control name. @returns @true if the control was successfully created or @false if - creation failed. + creation failed. */ - bool Create(wxWindow * parent, wxWindowID id, + bool Create(wxWindow* parent, wxWindowID id, const wxString& label, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, @@ -165,7 +158,7 @@ public: Returns a pointer to the pane window. Add controls to the returned wxWindow to make them collapsible. */ - wxWindow * GetPane(); + wxWindow* GetPane(); /** Returns @true if the pane window is currently hidden. diff --git a/interface/colordlg.h b/interface/colordlg.h index 37d350fc8a..b5df29b264 100644 --- a/interface/colordlg.h +++ b/interface/colordlg.h @@ -30,9 +30,9 @@ public: or replaced with white colour on platforms where custom colours palette has fixed size (MSW). - @sa wxColourData + @see wxColourData */ - wxColourDialog(wxWindow* parent, wxColourData* data = @NULL); + wxColourDialog(wxWindow* parent, wxColourData* data = NULL); /** Destructor. @@ -42,7 +42,7 @@ public: /** Same as @ref ctor() constructor. */ - bool Create(wxWindow* parent, wxColourData* data = @NULL); + bool Create(wxWindow* parent, wxColourData* data = NULL); /** Returns the @ref overview_wxcolourdata "colour data" associated with the colour @@ -68,21 +68,19 @@ public: is valid) if the dialog was cancelled. @param parent - The parent window for the colour selection dialog - + The parent window for the colour selection dialog @param colInit - If given, this will be the colour initially selected in the dialog. - + If given, this will be the colour initially selected in the dialog. @param caption - If given, this will be used for the dialog caption. - + If given, this will be used for the dialog caption. @param data - Optional object storing additional colour dialog settings, such - as custom colours. If none is provided the same settings as the last time are - used. + Optional object storing additional colour dialog settings, such + as custom colours. If none is provided the same settings as the last time + are + used. */ -wxColour wxGetColourFromUser(wxWindow * parent, +wxColour wxGetColourFromUser(wxWindow* parent, const wxColour& colInit, const wxString& caption = wxEmptyString, - wxColourData * data = @NULL); + wxColourData* data = NULL); diff --git a/interface/colour.h b/interface/colour.h index bc5673324d..9d29536bd0 100644 --- a/interface/colour.h +++ b/interface/colour.h @@ -52,30 +52,25 @@ public: Copy constructor. @param red - The red value. - + The red value. @param green - The green value. - + The green value. @param blue - The blue value. - + The blue value. @param alpha - The alpha value. Alpha values range from 0 (wxALPHA_TRANSPARENT) to 255 + The alpha value. Alpha values range from 0 (wxALPHA_TRANSPARENT) to 255 (wxALPHA_OPAQUE). - @param colourName - The colour name. - + The colour name. @param colour - The colour to copy. + The colour to copy. - @sa wxColourDatabase + @see wxColourDatabase */ wxColour(); wxColour(unsigned char red, unsigned char green, unsigned char blue, - unsigned char alpha=wxALPHA_OPAQUE); + unsigned char alpha = wxALPHA_OPAQUE); wxColour(const wxString& colourNname); wxColour(const wxColour& colour); //@} @@ -95,7 +90,6 @@ public: /** is not specified in flags. - This function is new since wxWidgets version 2.7.0 */ wxString GetAsString(long flags); @@ -113,7 +107,6 @@ public: Returns a pixel value which is platform-dependent. On Windows, a COLORREF is returned. On X, an allocated pixel value is returned. - -1 is returned if the pixel is invalid (on X, unallocated). */ long GetPixel(); @@ -127,33 +120,30 @@ public: Returns @true if the colour object is valid (the colour has been initialised with RGB values). */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** Returns the red intensity. */ -#define unsigned char Red() /* implementation is private */ + unsigned char Red(); //@{ /** Sets the RGB intensity values using the given values (first overload), extracting them from the packed long (second overload), using the given string (third overloard). - When using third form, Set() accepts: colour names (those listed in wxTheColourDatabase), the CSS-like @c "rgb(r,g,b)" or @c "rgba(r,g,b,a)" syntax (case insensitive) and the HTML-like syntax (i.e. @c "#" followed by 6 hexadecimal digits for red, green, blue components). - Returns @true if the conversion was successful, @false otherwise. - This function is new since wxWidgets version 2.7.0 */ void Set(unsigned char red, unsigned char green, unsigned char blue, - unsigned char alpha=wxALPHA_OPAQUE); + unsigned char alpha = wxALPHA_OPAQUE); void Set(unsigned long RGB); - bool Set(const wxString & str); + bool Set(const wxString& str); //@} /** @@ -166,7 +156,7 @@ public: /** Assignment operator, using a colour name to be found in the colour database. - @sa wxColourDatabase + @see wxColourDatabase */ wxColour operator =(const wxColour& colour); wxColour operator =(const wxString& colourName); diff --git a/interface/combo.h b/interface/combo.h index 24ca4e595a..a5538d654b 100644 --- a/interface/combo.h +++ b/interface/combo.h @@ -48,15 +48,13 @@ public: for the popup control, according to the variables given. @param minWidth - Preferred minimum width. - + Preferred minimum width. @param prefHeight - Preferred height. May be -1 to indicate - no preference. - + Preferred height. May be -1 to indicate + no preference. @param maxWidth - Max height for window, as limited by - screen size. + Max height for window, as limited by + screen size. @remarks Called each time popup is about to be shown. */ @@ -85,7 +83,6 @@ public: /** Utility method that returns @true if Create has been called. - Useful in conjunction with LazyCreate(). */ bool IsCreated(); @@ -110,7 +107,6 @@ public: /** The derived class may implement this to receive key events from the parent wxComboCtrl. - Events not handled should be skipped, as usual. */ void OnComboKeyEvent(wxKeyEvent& event); @@ -130,7 +126,6 @@ public: /** The derived class may implement this to paint the parent wxComboCtrl. - Default implementation draws value as string. */ void PaintComboControl(wxDC& dc, const wxRect& rect); @@ -143,7 +138,6 @@ public: /** wxComboCtrl m_combo - Parent wxComboCtrl. This is parameter has been prepared before Init() is called. */ @@ -179,9 +173,9 @@ public: @endStyleTable @beginEventTable - @event{EVT_TEXT(id\, func)}: + @event{EVT_TEXT(id, func)}: Process a wxEVT_COMMAND_TEXT_UPDATED event, when the text changes. - @event{EVT_TEXT_ENTER(id\, func)}: + @event{EVT_TEXT_ENTER(id, func)}: Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in the combo control. @endEventTable @@ -201,31 +195,25 @@ public: Constructor, creating and showing a combo control. @param parent - Parent window. Must not be @NULL. - + Parent window. Must not be @NULL. @param id - Window identifier. The value wxID_ANY indicates a default value. - + Window identifier. The value wxID_ANY indicates a default value. @param value - Initial selection string. An empty string indicates no selection. - + Initial selection string. An empty string indicates no selection. @param pos - Window position. - + Window position. @param size - Window size. If wxDefaultSize is specified then the window is sized - appropriately. - + Window size. If wxDefaultSize is specified then the window is + sized + appropriately. @param style - Window style. See wxComboCtrl. - + Window style. See wxComboCtrl. @param validator - Window validator. - + Window validator. @param name - Window name. + Window name. - @sa Create(), wxValidator + @see Create(), wxValidator */ wxComboCtrl(); wxComboCtrl(wxWindow* parent, wxWindowID id, @@ -248,8 +236,8 @@ public: custom popup animation. @returns @true if animation finishes before the function returns. @false - otherwise. In the latter case you need to manually - call DoShowPopup after the animation ends. + otherwise. In the latter case you need to manually call + DoShowPopup after the animation ends. */ virtual bool AnimateShow(const wxRect& rect, int flags); @@ -274,13 +262,12 @@ public: /** Copies the selected text to the clipboard and removes the selection. */ -#define void Cut() /* implementation is private */ + void Cut(); /** This member function is not normally called in application code. Instead, it can be implemented in a derived class to return default wxComboPopup, incase @c popup is @NULL. - @b Note: If you have implemented OnButtonClick to do something else than show the popup, then DoSetPopupControl must always return @NULL. @@ -295,10 +282,9 @@ public: the animation within it's function scope). @param rect - Position to show the popup window at, in screen coordinates. - + Position to show the popup window at, in screen coordinates. @param flags - Combination of any of the following: + Combination of any of the following: */ virtual void DoShowPopup(const wxRect& rect, int flags); @@ -306,7 +292,7 @@ public: Enables or disables popup animation, if any, depending on the value of the argument. */ - void EnablePopupAnimation(bool enable = @true); + void EnablePopupAnimation(bool enable = true); /** Returns disabled button bitmap that has been set with @@ -348,7 +334,7 @@ public: /** Returns custom painted area in control. - @sa SetCustomPaintWidth(). + @see SetCustomPaintWidth(). */ int GetCustomPaintWidth(); @@ -363,7 +349,6 @@ public: /** Returns the insertion point for the combo control's text field. - @b Note: Under wxMSW, this function always returns 0 if the combo control doesn't have the focus. */ @@ -420,21 +405,17 @@ public: Returns @true if the popup window is in the given state. Possible values are: - @c Hidden() - Popup window is hidden. @c Animating() - Popup window is being shown, but the popup animation has not yet finished. @c Visible() - Popup window is fully visible. */ bool IsPopupWindowState(int state); @@ -442,9 +423,7 @@ public: /** Implement in a derived class to define what happens on dropdown button click. - Default action is to show the popup. - @b Note: If you implement this to do something else than show the popup, you must then also implement DoSetPopupControl() to always @@ -461,10 +440,9 @@ public: Removes the text between the two positions in the combo control text field. @param from - The first position. - + The first position. @param to - The last position. + The last position. */ void Remove(long from, long to); @@ -473,13 +451,11 @@ public: control text field. @param from - The first position. - + The first position. @param to - The second position. - + The second position. @param text - The text to insert. + The text to insert. */ void Replace(long from, long to, const wxString& value); @@ -487,25 +463,21 @@ public: Sets custom dropdown button graphics. @param bmpNormal - Default button image. - + Default button image. @param pushButtonBg - If @true, blank push button background is painted - below the image. - + If @true, blank push button background is painted + below the image. @param bmpPressed - Depressed button image. - + Depressed button image. @param bmpHover - Button image when mouse hovers above it. This - should be ignored on platforms and themes that do not generally draw - different kind of button on mouse hover. - + Button image when mouse hovers above it. This + should be ignored on platforms and themes that do not generally draw + different kind of button on mouse hover. @param bmpDisabled - Disabled button image. + Disabled button image. */ void SetButtonBitmaps(const wxBitmap& bmpNormal, - bool pushButtonBg = @false, + bool pushButtonBg = false, const wxBitmap& bmpPressed = wxNullBitmap, const wxBitmap& bmpHover = wxNullBitmap, const wxBitmap& bmpDisabled = wxNullBitmap); @@ -514,17 +486,14 @@ public: Sets size and position of dropdown button. @param width - Button width. Value = 0 specifies default. - + Button width. Value = 0 specifies default. @param height - Button height. Value = 0 specifies default. - + Button height. Value = 0 specifies default. @param side - Indicates which side the button will be placed. - Value can be wxLEFT or wxRIGHT. - + Indicates which side the button will be placed. + Value can be wxLEFT or wxRIGHT. @param spacingX - Horizontal spacing around the button. Default is 0. + Horizontal spacing around the button. Default is 0. */ void SetButtonPosition(int width = -1, int height = -1, int side = wxRIGHT, @@ -541,7 +510,7 @@ public: Sets the insertion point in the text field. @param pos - The new insertion point. + The new insertion point. */ void SetInsertionPoint(long pos); @@ -569,12 +538,11 @@ public: Extends popup size horizontally, relative to the edges of the combo control. @param extLeft - How many pixel to extend beyond the left edge of the - control. Default is 0. - + How many pixel to extend beyond the left edge of the + control. Default is 0. @param extRight - How many pixel to extend beyond the right edge of the - control. Default is 0. + How many pixel to extend beyond the right edge of the + control. Default is 0. @remarks Popup minimum width may override arguments. */ @@ -599,10 +567,9 @@ public: Selects the text between the two positions, in the combo control text field. @param from - The first position. - + The first position. @param to - The second position. + The second position. */ void SetSelection(long from, long to); @@ -622,7 +589,6 @@ public: /** Sets the text for the combo control text field. - @b NB: 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 @@ -635,7 +601,7 @@ public: if @c withEvent is @true. */ void SetValueWithEvent(const wxString& value, - bool withEvent = @true); + bool withEvent = true); /** Show the popup. @@ -654,5 +620,5 @@ public: and as such, when it is shown, its parent top-level window will appear as if the focus has been lost from it. */ - void UseAltPopupWindow(bool enable = @true); + void UseAltPopupWindow(bool enable = true); }; diff --git a/interface/combobox.h b/interface/combobox.h index 1302069b8e..b47bb712dc 100644 --- a/interface/combobox.h +++ b/interface/combobox.h @@ -41,14 +41,14 @@ @endStyleTable @beginEventTable - @event{EVT_COMBOBOX(id\, func)}: + @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 value of selection. - @event{EVT_TEXT(id\, func)}: + @event{EVT_TEXT(id, func)}: Process a wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text changes. - @event{EVT_TEXT_ENTER(id\, func)}: + @event{EVT_TEXT_ENTER(id, func)}: Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in the combobox (notice that the combobox must have been created with wxTE_PROCESS_ENTER style to receive this event). @@ -69,37 +69,29 @@ public: Constructor, creating and showing a combobox. @param parent - Parent window. Must not be @NULL. - + Parent window. Must not be @NULL. @param id - Window identifier. The value wxID_ANY indicates a default value. - + Window identifier. The value wxID_ANY indicates a default value. @param value - Initial selection string. An empty string indicates no selection. - + Initial selection string. An empty string indicates no selection. @param pos - Window position. - + Window position. @param size - Window size. If wxDefaultSize is specified then the window is sized - appropriately. - + Window size. If wxDefaultSize is specified then the window is + sized + appropriately. @param n - Number of strings with which to initialise the control. - + Number of strings with which to initialise the control. @param choices - An array of strings with which to initialise the control. - + An array of strings with which to initialise the control. @param style - Window style. See wxComboBox. - + Window style. See wxComboBox. @param validator - Window validator. - + Window validator. @param name - Window name. + Window name. - @sa Create(), wxValidator + @see Create(), wxValidator */ wxComboBox(); wxComboBox(wxWindow* parent, wxWindowID id, @@ -107,7 +99,7 @@ public: const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, int n = 0, - const wxString choices[] = @NULL, + const wxString choices[] = NULL, long style = 0, const wxValidator& validator = wxDefaultValidator, const wxString& name = "comboBox"); @@ -191,7 +183,7 @@ public: /** Copies the selected text to the clipboard and removes the selection. */ -#define void Cut() /* implementation is private */ + void Cut(); /** This function does the same things as @@ -203,7 +195,6 @@ public: /** Returns the insertion point for the combobox's text field. - @b Note: Under wxMSW, this function always returns 0 if the combobox doesn't have the focus. */ @@ -218,10 +209,9 @@ public: This is the same as wxTextCtrl::GetSelection for the text control which is part of the combobox. Notice that this is a different method from wxControlWithItems::GetSelection. - Currently this method is only implemented in wxMSW and wxGTK. */ - void GetSelection(long * from, long * to); + void GetSelection(long* from, long* to); /** Returns the current value in the combobox text field. @@ -242,10 +232,9 @@ public: Removes the text between the two positions in the combobox text field. @param from - The first position. - + The first position. @param to - The last position. + The last position. */ void Remove(long from, long to); @@ -254,13 +243,11 @@ public: text field. @param from - The first position. - + The first position. @param to - The second position. - + The second position. @param text - The text to insert. + The text to insert. */ void Replace(long from, long to, const wxString& text); @@ -268,7 +255,7 @@ public: Sets the insertion point in the combobox text field. @param pos - The new insertion point. + The new insertion point. */ void SetInsertionPoint(long pos); @@ -281,21 +268,19 @@ public: Selects the text between the two positions, in the combobox text field. @param from - The first position. - + The first position. @param to - The second position. + The second position. */ void SetSelection(long from, long to); /** 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. @param text - The text to set. + The text to set. */ void SetValue(const wxString& text); diff --git a/interface/config.h b/interface/config.h index 9aafb047b3..0f9bf1a69d 100644 --- a/interface/config.h +++ b/interface/config.h @@ -39,75 +39,70 @@ class wxConfigBase : public wxObject public: /** ) - This is the default and only constructor of the wxConfigBase class, and derived classes. @param appName - The application name. If this is empty, the class will - normally use wxApp::GetAppName to set it. The - application name is used in the registry key on Windows, and can be used to - deduce the local filename parameter if that is missing. - + The application name. If this is empty, the class will + normally use wxApp::GetAppName to set it. The + application name is used in the registry key on Windows, and can be used to + deduce the local filename parameter if that is missing. @param vendorName - The vendor name. If this is empty, it is assumed that - no vendor name is wanted, if this is optional for the current config class. - The vendor name is appended to the application name for wxRegConfig. - + The vendor name. If this is empty, it is assumed that + no vendor name is wanted, if this is optional for the current config class. + The vendor name is appended to the application name for wxRegConfig. @param localFilename - Some config classes require a local filename. If this - is not present, but required, the application name will be used instead. - + Some config classes require a local filename. If this + is not present, but required, the application name will be used instead. @param globalFilename - Some config classes require a global filename. If - this is not present, but required, the application name will be used instead. - + Some config classes require a global filename. If + this is not present, but required, the application name will be used + instead. @param style - Can be one of wxCONFIG_USE_LOCAL_FILE and - wxCONFIG_USE_GLOBAL_FILE. The style interpretation depends on the config - class and is ignored by some implementations. For wxFileConfig, these styles - determine whether a local or global config file is created or used: if - wxCONFIG_USE_GLOBAL_FILE is used, then settings are read from the global - config file and if wxCONFIG_USE_LOCAL_FILE is used, settings are read from - and written to local config file (if they are both set, global file is read - first, then local file, overwriting global settings). If the - flag is present but the parameter is empty, the parameter will be set to a - default. If the parameter is present but the style flag not, the relevant flag - will be added to the style. For wxRegConfig, thie GLOBAL flag refers to HKLM - key while LOCAL one is for the usual HKCU one. - - For wxFileConfig you can also add wxCONFIG_USE_RELATIVE_PATH by logically - or'ing it to either of the _FILE options to tell wxFileConfig to use relative - instead of absolute paths. - - On non-VMS Unix systems, the default local configuration file is ~/.appname. - However, this path may be also used as user data directory - (see wxStandardPaths::GetUserDataDir) if - the application has several data files. In this case wxCONFIG_USE_SUBDIR - flag, which changes the default local configuration file to ~/.appname/appname - should be used. Notice that this flag is ignored if localFilename is - provided. This function is new since wxWidgets version 2.8.2 - - For wxFileConfig, you can also add wxCONFIG_USE_NO_ESCAPE_CHARACTERS which - will turn off character escaping for the values of entries stored in the config - file: for example a foo key with some backslash characters will be stored - as foo=C:\mydir instead of the usual storage of - foo=C:\\mydir. - - The wxCONFIG_USE_NO_ESCAPE_CHARACTERS style can be helpful if your config - file must be read or written to by a non-wxWidgets program (which might not - understand the escape characters). Note, however, that if - wxCONFIG_USE_NO_ESCAPE_CHARACTERS style is used, it is is now - your application's responsibility to ensure that there is no newline or - other illegal characters in a value, before writing that value to the file. - + Can be one of wxCONFIG_USE_LOCAL_FILE and + wxCONFIG_USE_GLOBAL_FILE. The style interpretation depends on the config + class and is ignored by some implementations. For wxFileConfig, these styles + determine whether a local or global config file is created or used: if + wxCONFIG_USE_GLOBAL_FILE is used, then settings are read from the global + config file and if wxCONFIG_USE_LOCAL_FILE is used, settings are read from + and written to local config file (if they are both set, global file is read + first, then local file, overwriting global settings). If the + flag is present but the parameter is empty, the parameter will be set to a + default. If the parameter is present but the style flag not, the relevant + flag + will be added to the style. For wxRegConfig, thie GLOBAL flag refers to HKLM + key while LOCAL one is for the usual HKCU one. + For wxFileConfig you can also add wxCONFIG_USE_RELATIVE_PATH by logically + or'ing it to either of the _FILE options to tell wxFileConfig to use + relative + instead of absolute paths. + On non-VMS Unix systems, the default local configuration file is ~/.appname. + However, this path may be also used as user data directory + (see wxStandardPaths::GetUserDataDir) if + the application has several data files. In this case wxCONFIG_USE_SUBDIR + flag, which changes the default local configuration file to + ~/.appname/appname + should be used. Notice that this flag is ignored if localFilename is + provided. This function is new since wxWidgets version 2.8.2 + For wxFileConfig, you can also add wxCONFIG_USE_NO_ESCAPE_CHARACTERS which + will turn off character escaping for the values of entries stored in the + config + file: for example a foo key with some backslash characters will be stored + as foo=C:\mydir instead of the usual storage of + foo=C:\\mydir. + The wxCONFIG_USE_NO_ESCAPE_CHARACTERS style can be helpful if your config + file must be read or written to by a non-wxWidgets program (which might not + understand the escape characters). Note, however, that if + wxCONFIG_USE_NO_ESCAPE_CHARACTERS style is used, it is is now + your application's responsibility to ensure that there is no newline or + other illegal characters in a value, before writing that value to the file. @param conv - This parameter is only used by wxFileConfig when compiled - in Unicode mode. It specifies the encoding in which the configuration file - is written. + This parameter is only used by wxFileConfig when compiled + in Unicode mode. It specifies the encoding in which the configuration file + is written. @remarks By default, environment variable expansion is on and recording - defaults is off. + defaults is off. */ wxConfigBase(const wxString& appName = wxEmptyString, const wxString& vendorName = wxEmptyString, @@ -133,13 +128,12 @@ public: near the definition of wxCONFIG_WIN32_NATIVE for details. It returns the created object and also sets it as the current one. */ - static wxConfigBase * Create(); + static wxConfigBase* Create(); /** The functions in this section delete entries and/or groups of entries from the config file. @e DeleteAll() is especially useful if you want to erase all traces of your program presence: for example, when you uninstall it. - DeleteEntry() DeleteGroup() @@ -159,7 +153,7 @@ public: in it and the second parameter is @true. */ bool DeleteEntry(const wxString& key, - bool bDeleteGroupIfEmpty = @true); + bool bDeleteGroupIfEmpty = true); /** Delete the group (with all subgroups). If the current path is under the group @@ -179,7 +173,6 @@ public: /** The functions in this section allow to enumerate all entries and groups in the config file. All functions here return @false when there are no more items. - You must pass the same index to GetNext and GetFirst (don't modify it). Please note that it is @b not the index of the current item (you will have some great surprises with wxRegConfig if you assume this) and you shouldn't @@ -187,11 +180,10 @@ public: enumeration. It can't be stored inside the class because it would prevent you from running several enumerations simultaneously, that's why you must pass it explicitly. - Having said all this, enumerating the config entries/groups is very simple: + There are also functions to get the number of entries/subgroups without actually enumerating them, but you will probably never need them. - GetFirstGroup() GetNextGroup() @@ -215,14 +207,14 @@ public: permanently writes all changes (otherwise, they're only written from object's destructor) */ - bool Flush(bool bCurrentOnly = @false); + bool Flush(bool bCurrentOnly = false); /** Get the current config object. If there is no current object and - @e CreateOnDemand is @true, creates one + @a CreateOnDemand is @true, creates one (using @e Create) unless DontCreateOnDemand was called previously. */ -#define static wxConfigBase * Get(bool CreateOnDemand = @true) /* implementation is private */ + static wxConfigBase* Get(bool CreateOnDemand = true); /** Returns the application name. @@ -235,7 +227,6 @@ public: be used because some of wxConfig implementations will complain about type mismatch otherwise: e.g., an attempt to read a string value from an integer key with wxRegConfig will fail. - The result is an element of enum EntryType: */ enum wxConfigBase::EntryType GetEntryType(const wxString& name); @@ -263,13 +254,13 @@ public: /** */ - uint GetNumberOfEntries(bool bRecursive = @false); + uint GetNumberOfEntries(bool bRecursive = false); /** Get number of entries/subgroups in the current group, with or without its subgroups. */ - uint GetNumberOfGroups(bool bRecursive = @false); + uint GetNumberOfGroups(bool bRecursive = false); /** Retrieve the current path (always as absolute path). @@ -305,21 +296,17 @@ public: These function are the core of wxConfigBase class: they allow you to read and write config file data. All @e Read function take a default value which will be returned if the specified key is not found in the config file. - Currently, supported types of data are: wxString, @e long, @e double, @e bool, wxColour and any other types, for which functions wxToString and wxFromString are defined. - Try not to read long values into string variables and vice versa: although it just might work with wxFileConfig, you will get a system error with wxRegConfig because in the Windows registry the different types of entries are indeed used. - Final remark: the @e szKey parameter for all these functions can contain an arbitrary path (either relative or absolute), not just the key name. - Read() Write() @@ -342,18 +329,16 @@ public: first of them is the expansion of environment variables in the string values read from the config file: for example, if you have the following in your config file: + the call to @c config-Read("UserData") will return something like @c "/home/zeitlin/data" if you're lucky enough to run a Linux system ;-) - Although this feature is very useful, it may be annoying if you read a value which containts '$' or '%' symbols (% is used for environment variables expansion under Windows) which are not used for environment variable expansion. In this situation you may call SetExpandEnvVars(@false) just before reading this value and SetExpandEnvVars(@true) just after. Another solution would be to prefix the offending symbols with a backslash. - The following functions control this option: - IsExpandingEnvVars() SetExpandEnvVars() @@ -373,14 +358,16 @@ public: which makes it possible to use the relative paths. To clarify all this, here is an example (it is only for the sake of demonstration, it doesn't do anything sensible!): + @e Warning: it is probably a good idea to always restore the path to its old value on function exit: + because otherwise the assert in the following example will surely fail (we suppose here that @e foo() function is the same as above except that it doesn't save and restore the path): + Finally, the path separator in wxConfigBase and derived classes is always '/', regardless of the platform (i.e. it is @b not '\\' under Windows). - SetPath() GetPath() @@ -392,30 +379,24 @@ public: Reads a value of type T, for which function wxFromString is defined, returning @true if the value was found. - If the value was not found, @e defaultVal is used instead. - + If the value was not found, @a defaultVal is used instead. bool Read(const wxStringkey, T* value) const; - @b Read(key, default="") - Returns a string @b ReadInt(key, default=0) - Returns an integer @b ReadFloat(key, default=0.0) - Returns a floating point number @b ReadBool(key, default=0) - Returns a boolean */ bool Read(const wxString& key, wxString* str); @@ -437,19 +418,19 @@ public: //@} /** - Reads a bool value from the key and returns it. @e defaultVal is returned + Reads a bool value from the key and returns it. @a defaultVal is returned if the key is not found. */ long ReadBool(const wxString& key, bool defaultVal); /** - Reads a double value from the key and returns it. @e defaultVal is returned + Reads a double value from the key and returns it. @a defaultVal is returned if the key is not found. */ long ReadDouble(const wxString& key, double defaultVal); /** - Reads a long value from the key and returns it. @e defaultVal is returned + Reads a long value from the key and returns it. @a defaultVal is returned if the key is not found. */ long ReadLong(const wxString& key, long defaultVal); @@ -457,7 +438,7 @@ public: /** Reads a value of type T, for which function wxFromString is defined, from the key and returns it. - @e defaultVal is returned if the key is not found. + @a defaultVal is returned if the key is not found. */ T ReadObject(const wxString& key, T const& defaultVal); @@ -467,7 +448,6 @@ public: entry/group with the original name doesn't exist, because the entry/group with the new name already exists or because the function is not supported in this wxConfig implementation. - RenameEntry() RenameGroup() @@ -478,8 +458,7 @@ public: Renames an entry in the current group. The entries names (both the old and the new one) shouldn't contain backslashes, i.e. only simple names and not arbitrary paths are accepted by this function. - - Returns @false if @e oldName doesn't exist or if @e newName already + Returns @false if @a oldName doesn't exist or if @a newName already exists. */ bool RenameEntry(const wxString& oldName, @@ -489,8 +468,7 @@ public: Renames a subgroup of the current group. The subgroup names (both the old and the new one) shouldn't contain backslashes, i.e. only simple names and not arbitrary paths are accepted by this function. - - Returns @false if @e oldName doesn't exist or if @e newName already + Returns @false if @a oldName doesn't exist or if @a newName already exists. */ bool RenameGroup(const wxString& oldName, @@ -500,12 +478,12 @@ public: Sets the config object as the current one, returns the pointer to the previous current object (both the parameter and returned value may be @NULL) */ -#define static wxConfigBase * Set(wxConfigBase * pConfig) /* implementation is private */ + static wxConfigBase* Set(wxConfigBase* pConfig); /** Determine whether we wish to expand environment variables in key values. */ - void SetExpandEnvVars(bool bDoIt = @true); + void SetExpandEnvVars(bool bDoIt = true); /** Set current path: if the first character is '/', it is the absolute path, @@ -517,12 +495,11 @@ public: /** Sets whether defaults are recorded to the config file whenever an attempt to read the value which is not present in it is done. - If on (default is off) all default values for the settings used by the program are written back to the config file. This allows the user to see what config options may be changed and is probably useful only for wxFileConfig. */ - void SetRecordDefaults(bool bDoIt = @true); + void SetRecordDefaults(bool bDoIt = true); /** These functions deal with the "default" config object. Although its usage is @@ -536,17 +513,14 @@ public: exists. Note that this implies that if you do delete this object yourself (usually in wxApp::OnExit) you must use @e Set(@NULL) to prevent wxWidgets from deleting it the second time. - As it happens, you may even further simplify the procedure described above: you may forget about calling @e Set(). When @e Get() is called and there is no current object, it will create one using @e Create() function. To disable this behaviour @e DontCreateOnDemand() is provided. - @b Note: You should use either @e Set() or @e Get() because wxWidgets library itself would take advantage of it and could save various information in it. For example wxFontMapper or Unix version of wxFileDialog have the ability to use wxConfig class. - Set() Get() @@ -575,25 +549,20 @@ public: defined for type @e T. - @b Write(key, value) - Writes a string @b WriteInt(key, value) - Writes an integer @b WriteFloat(key, value) - Writes a floating point number @b WriteBool(key, value) - Writes a boolean */ bool Write(const wxString& key, const wxString& value); diff --git a/interface/control.h b/interface/control.h index eb7699f174..16796de2a3 100644 --- a/interface/control.h +++ b/interface/control.h @@ -33,7 +33,6 @@ public: /** Returns the control's text. - Note that the returned string contains the mnemonics (@c characters) if any, use GetLabelText() if they are undesired. @@ -42,7 +41,7 @@ public: //@{ /** - Returns the control's label, or the given @e label string for the static + Returns the control's label, or the given @a label string for the static version, without the mnemonics characters. */ const wxString GetLabelText(); @@ -51,8 +50,7 @@ public: /** Sets the item's text. - - The @c characters in the @e label are special and indicate that the + The @c characters in the @a label are special and indicate that the following character is a mnemonic for this control and can be used to activate it from the keyboard (typically by using @e Alt key in combination with it). To insert a literal ampersand character, you need to double it, i.e. use diff --git a/interface/convauto.h b/interface/convauto.h index 12770bbb4f..abd98afcb0 100644 --- a/interface/convauto.h +++ b/interface/convauto.h @@ -52,7 +52,7 @@ public: Constructs a new wxConvAuto instance. The object will try to detect the input of the multibyte text given to its wxMBConv::ToWChar method automatically but if the automatic detection of Unicode encodings fails, the - fall-back encoding @e enc will be used to interpret it as multibyte text. + fall-back encoding @a enc will be used to interpret it as multibyte text. The default value of this parameter, @c wxFONTENCODING_DEFAULT means that the global default value which can be set using @ref setdefaultmbencoding() SetFallbackEncoding method should be @@ -87,9 +87,8 @@ public: explicitly specified in constructor. The default value, which can be retrieved using @ref getdefaultmbencoding() GetFallbackEncoding, is @c wxFONTENCODING_ISO8859_1. - Special values of @c wxFONTENCODING_SYSTEM or - @c wxFONTENCODING_MAX can be used for @e enc parameter to use the + @c wxFONTENCODING_MAX can be used for @a enc parameter to use the encoding of the current user locale as fall back or not use any encoding for fall back at all, respectively (just as with the similar constructor parameter). However @c wxFONTENCODING_DEFAULT value cannot be used here. diff --git a/interface/cpp.h b/interface/cpp.h index cebc29a50e..38898b058c 100644 --- a/interface/cpp.h +++ b/interface/cpp.h @@ -12,10 +12,10 @@ Unlike when using the preprocessor @c operator, the arguments undergo the macro expansion before being concatenated. */ -wxCONCAT(x1, x2); -wxCONCAT3(x1, x2, x3); -wxCONCAT4(x1, x2, x3, x4); -wxCONCAT5(x1, x2, x3, x4, x5); +wxCONCAT(x1, x2); +wxCONCAT3(x1, x2, x3); +wxCONCAT4(x1, x2, x3, x4); +wxCONCAT5(x1, x2, x3, x4, x5); //@} @@ -23,11 +23,10 @@ wxCONCAT5(x1, x2, x3, x4, x5); Returns the string representation of the given symbol which can be either a literal or a macro (hence the advantage of using this macro instead of the standard preprocessor @c # operator which doesn't work with macros). - Notice that this macro always produces a @c char string, use wxSTRINGIZE_T to build a wide string Unicode build. -@sa wxCONCAT +@see wxCONCAT */ #define wxSTRINGIZE(x) /* implementation is private */ diff --git a/interface/cshelp.h b/interface/cshelp.h index f4ac5beca0..054e8e3626 100644 --- a/interface/cshelp.h +++ b/interface/cshelp.h @@ -43,7 +43,7 @@ public: Unlike some other classes, the help provider is not created on demand. This must be explicitly done by the application. */ -#define wxHelpProvider* Get() /* implementation is private */ + wxHelpProvider* Get(); //@{ /** @@ -67,13 +67,12 @@ public: Get/set the current, application-wide help provider. Returns the previous one. */ -#define wxHelpProvider* Set(wxHelpProvider* helpProvider) /* implementation is private */ + wxHelpProvider* Set(wxHelpProvider* helpProvider); /** Shows help for the given window. Override this function if the help doesn't depend on the exact position inside the window, otherwise you need to override ShowHelpAtPoint(). - Returns @true if help was shown, or @false if no help was available for this window. */ @@ -84,18 +83,15 @@ public: depend on the position inside the window, By default this method forwards to ShowHelp(), so it is enough to only implement the latter if the help doesn't depend on the position. - Returns @true if help was shown, or @false if no help was available for this window. @param window - Window to show help text for. - + Window to show help text for. @param point - Coordinates of the mouse at the moment of help event emission. - + Coordinates of the mouse at the moment of help event emission. @param origin - Help event origin, see wxHelpEvent::GetOrigin. + Help event origin, see wxHelpEvent::GetOrigin. */ bool ShowHelpAtPoint(wxWindowBase* window, const wxPoint point, wxHelpEvent::Origin origin); @@ -134,7 +130,7 @@ public: Note that the instance doesn't own the help controller. The help controller should be deleted separately. */ - wxHelpControllerHelpProvider(wxHelpControllerBase* hc = @NULL); + wxHelpControllerHelpProvider(wxHelpControllerBase* hc = NULL); /** Returns the help controller associated with this help provider. @@ -192,11 +188,10 @@ class wxContextHelp : public wxObject public: /** Constructs a context help object, calling BeginContextHelp() if - @e doNow is @true (the default). - - If @e window is @NULL, the top window is used. + @a doNow is @true (the default). + If @a window is @NULL, the top window is used. */ - wxContextHelp(wxWindow* window = @NULL, bool doNow = @true); + wxContextHelp(wxWindow* window = NULL, bool doNow = true); /** Destroys the context help object. @@ -204,14 +199,13 @@ public: ~wxContextHelp(); /** - Puts the application into context-sensitive help mode. @e window is the window + Puts the application into context-sensitive help mode. @a window is the window which will be used to catch events; if @NULL, the top window will be used. - Returns @true if the application was successfully put into context-sensitive help mode. This function only returns when the event loop has finished. */ - bool BeginContextHelp(wxWindow* window = @NULL); + bool BeginContextHelp(wxWindow* window = NULL); /** Ends context-sensitive help mode. Not normally called by the application. @@ -249,20 +243,17 @@ public: Constructor, creating and showing a context help button. @param parent - Parent window. Must not be @NULL. - + Parent window. Must not be @NULL. @param id - Button identifier. Defaults to wxID_CONTEXT_HELP. - + Button identifier. Defaults to wxID_CONTEXT_HELP. @param pos - Button position. - + Button position. @param size - Button size. If wxDefaultSize is specified then the button is sized - appropriately for the question mark bitmap. - + Button size. If wxDefaultSize is specified then the button is + sized + appropriately for the question mark bitmap. @param style - Window style. + Window style. */ wxContextHelpButton(); wxContextHelpButton(wxWindow* parent, diff --git a/interface/ctrlsub.h b/interface/ctrlsub.h index f0211eef44..3fcd78d351 100644 --- a/interface/ctrlsub.h +++ b/interface/ctrlsub.h @@ -48,39 +48,34 @@ public: of items. @param item - String to add. - + String to add. @param stringsArray - Contains items to append to the control. - + Contains items to append to the control. @param strings - Array of strings of size n. - + Array of strings of size n. @param n - Number of items in the strings array. - + Number of items in the strings array. @param clientData - Array of client data pointers of size n to associate with the new items. + Array of client data pointers of size n to associate with the new items. @returns When appending a single item, the return value is the index of - the newly added item which may be different from the - last one if the control is sorted (e.g. has wxLB_SORT - or wxCB_SORT style). + the newly added item which may be different from the + last one if the control is sorted (e.g. has wxLB_SORT + or wxCB_SORT style). */ int Append(const wxString& item); - int Append(const wxString& item, void * clientData); - int Append(const wxString& item, wxClientData * clientData); + int Append(const wxString& item, void* clientData); + int Append(const wxString& item, wxClientData* clientData); void Append(const wxArrayString& strings); void Append(unsigned int n, const wxString* strings); void Append(unsigned int n, const wxString* strings, - void ** clientData); + void** clientData); void Append(unsigned int n, const wxString* strings, - wxClientData ** clientData); + wxClientData** clientData); //@} /** Removes all items from the control. - @e Clear() also deletes the client data of the existing items if it is owned by the control. */ @@ -89,15 +84,14 @@ public: /** Deletes an item from the control. The client data associated with the item will be also deleted if it is owned by the control. - Note that it is an error (signalled by an assert failure in debug builds) to remove an item with the index negative or greater or equal than the number of items in the control. @param n - The zero-based item index. + The zero-based item index. - @sa Clear() + @see Clear() */ void Delete(unsigned int n); @@ -105,16 +99,15 @@ public: Finds an item whose label matches the given string. @param string - String to find. - + String to find. @param caseSensitive - Whether search is case sensitive (default is not). + Whether search is case sensitive (default is not). @returns The zero-based position of the item, or wxNOT_FOUND if the - string was not found. + string was not found. */ int FindString(const wxString& string, - bool caseSensitive = @false); + bool caseSensitive = false); /** Returns a pointer to the client data associated with the given item (if any). @@ -123,11 +116,11 @@ public: have any client data associated with it (but other items do). @param n - The zero-based position of the item. + The zero-based position of the item. @returns A pointer to the client data, or @NULL if not present. */ - void * GetClientData(unsigned int n); + void* GetClientData(unsigned int n); /** Returns a pointer to the client data associated with the given item (if any). @@ -136,16 +129,16 @@ public: have any client data associated with it (but other items do). @param n - The zero-based position of the item. + The zero-based position of the item. @returns A pointer to the client data, or @NULL if not present. */ - wxClientData * GetClientObject(unsigned int n); + wxClientData* GetClientObject(unsigned int n); /** Returns the number of items in the control. - @sa IsEmpty() + @see IsEmpty() */ unsigned int GetCount(); @@ -156,10 +149,10 @@ public: @returns The position of the current selection. @remarks This method can be used with single selection list boxes only, - you should use wxListBox::GetSelections for the list - boxes with wxLB_MULTIPLE style. + you should use wxListBox::GetSelections for the list + boxes with wxLB_MULTIPLE style. - @sa SetSelection(), GetStringSelection() + @see SetSelection(), GetStringSelection() */ int GetSelection(); @@ -167,10 +160,10 @@ public: Returns the label of the item with the given index. @param n - The zero-based index. + The zero-based index. @returns The label of the item or an empty string if the position was - invalid. + invalid. */ wxString GetString(unsigned int n); @@ -178,7 +171,7 @@ public: Returns the label of the selected item or an empty string if no item is selected. - @sa GetSelection() + @see GetSelection() */ wxString GetStringSelection(); @@ -195,47 +188,42 @@ public: of items. @param item - String to add. - + String to add. @param pos - Position to insert item before, zero based. - + Position to insert item before, zero based. @param stringsArray - Contains items to insert into the control content - + Contains items to insert into the control content @param strings - Array of strings of size n. - + Array of strings of size n. @param n - Number of items in the strings array. - + Number of items in the strings array. @param clientData - Array of client data pointers of size n to associate with the new items. + Array of client data pointers of size n to associate with the new items. @returns The return value is the index of the newly inserted item. If the - insertion failed for some reason, -1 is returned. + insertion failed for some reason, -1 is returned. */ int Insert(const wxString& item, unsigned int pos); int Insert(const wxString& item, unsigned int pos, - void * clientData); + void* clientData); int Insert(const wxString& item, unsigned int pos, - wxClientData * clientData); + wxClientData* clientData); void Insert(const wxArrayString& strings, unsigned int pos); void Insert(const wxArrayString& strings, unsigned int pos); void Insert(unsigned int n, const wxString* strings, unsigned int pos); void Insert(unsigned int n, const wxString* strings, unsigned int pos, - void ** clientData); + void** clientData); void Insert(unsigned int n, const wxString* strings, unsigned int pos, - wxClientData ** clientData); + wxClientData** clientData); //@} /** Returns @true if the control is empty or @false if it has some items. - @sa GetCount() + @see GetCount() */ bool IsEmpty(); @@ -253,37 +241,34 @@ public: append a lot of them. @param item - The single item to insert into the control. - + The single item to insert into the control. @param stringsArray - Contains items to set as control content. - + Contains items to set as control content. @param strings - Raw C++ array of strings. Only used in conjunction with 'n'. - + Raw C++ array of strings. Only used in conjunction with 'n'. @param n - Number of items passed in 'strings'. Only used in conjunction with 'strings'. - + Number of items passed in 'strings'. Only used in conjunction with + 'strings'. @param clientData - Client data to associate with the item(s). + Client data to associate with the item(s). @returns When the control is sorted (e.g. has wxLB_SORT or wxCB_SORT - style) the return value could be different from - (GetCount() - 1). When setting a single item to the - container, the return value is the index of the newly - added item which may be different from the last one - if the control is sorted (e.g. has wxLB_SORT or - wxCB_SORT style). + style) the return value could be different from + (GetCount() - 1). When setting a single item to the + container, the return value is the index of the newly + added item which may be different from the last one if + the control is sorted (e.g. has wxLB_SORT or wxCB_SORT + style). */ int Set(const wxString& item); - int Set(const wxString& item, void * clientData); - int Set(const wxString& item, wxClientData * clientData); + int Set(const wxString& item, void* clientData); + int Set(const wxString& item, wxClientData* clientData); void Set(const wxArrayString& stringsArray); void Set(unsigned int n, const wxString* strings); void Set(unsigned int n, const wxString* strings, - void ** clientData); + void** clientData); void Set(unsigned int n, const wxString* strings, - wxClientData ** clientData); + wxClientData** clientData); //@} /** @@ -292,41 +277,37 @@ public: associated with the control items before. @param n - The zero-based item index. - + The zero-based item index. @param data - The client data to associate with the item. + The client data to associate with the item. */ - void SetClientData(unsigned int n, void * data); + void SetClientData(unsigned int n, void* data); /** Associates the given typed client data pointer with the given item: the - @e data object will be deleted when the item is deleted (either explicitly + @a data object will be deleted when the item is deleted (either explicitly by using @ref delete() Deletes or implicitly when the control itself is destroyed). - Note that it is an error to call this function if any untyped client data pointers had been associated with the control items before. @param n - The zero-based item index. - + The zero-based item index. @param data - The client data to associate with the item. + The client data to associate with the item. */ - void SetClientObject(unsigned int n, wxClientData * data); + void SetClientObject(unsigned int n, wxClientData* data); /** - Sets the selection to the given item @e n or removes the selection entirely - if @e n == @c wxNOT_FOUND. - + Sets the selection to the given item @a n or removes the selection entirely + if @a n == @c wxNOT_FOUND. Note that this does not cause any command events to be emitted nor does it deselect any other items in the controls which support multiple selections. @param n - The string position to select, starting from zero. + The string position to select, starting from zero. - @sa SetString(), SetStringSelection() + @see SetString(), SetStringSelection() */ void SetSelection(int n); @@ -334,10 +315,9 @@ public: Sets the label for the given item. @param n - The zero-based item index. - + The zero-based item index. @param string - The label to set. + The label to set. */ void SetString(unsigned int n, const wxString& string); @@ -346,10 +326,10 @@ public: any command events to be emitted. @param string - The string to select. + The string to select. @returns @true if the specified string has been selected, @false if it - wasn't found in the control. + wasn't found in the control. */ bool SetStringSelection(const wxString& string); }; diff --git a/interface/cursor.h b/interface/cursor.h index 7d4a068f72..6395cecb98 100644 --- a/interface/cursor.h +++ b/interface/cursor.h @@ -48,211 +48,399 @@ public: Copy constructor, uses @ref overview_trefcount "reference counting". @param bits - An array of bits. - + An array of bits. @param maskBits - Bits for a mask bitmap. - + Bits for a mask bitmap. @param width - Cursor width. - + Cursor width. @param height - Cursor height. - + Cursor height. @param hotSpotX - Hotspot x coordinate. - + Hotspot x coordinate. @param hotSpotY - Hotspot y coordinate. - + Hotspot y coordinate. @param type - Icon type to load. Under Motif, type defaults to wxBITMAP_TYPE_XBM. Under + Icon type to load. Under Motif, type defaults to wxBITMAP_TYPE_XBM. Under Windows, - it defaults to wxBITMAP_TYPE_CUR_RESOURCE. Under MacOS, it defaults to + it defaults to wxBITMAP_TYPE_CUR_RESOURCE. Under MacOS, it defaults to wxBITMAP_TYPE_MACCURSOR_RESOURCE. + Under X, the permitted cursor types are: + + + + + + + + wxBITMAP_TYPE_XBM + + + + + Load an X bitmap file. + + + + + + Under Windows, the permitted types are: + + + + - Under X, the permitted cursor types are: - wxBITMAP_TYPE_XBM + wxBITMAP_TYPE_CUR - Load an X bitmap file. - Under Windows, the permitted types are: + Load a cursor from a .cur cursor file (only if USE_RESOURCE_LOADING_IN_MSW + is enabled in setup.h). - wxBITMAP_TYPE_CUR - Load a cursor from a .cur cursor file (only if USE_RESOURCE_LOADING_IN_MSW - is enabled in setup.h). - wxBITMAP_TYPE_CUR_RESOURCE + wxBITMAP_TYPE_CUR_RESOURCE - Load a Windows resource (as specified in the .rc file). - wxBITMAP_TYPE_ICO - Load a cursor from a .ico icon file (only if USE_RESOURCE_LOADING_IN_MSW - is enabled in setup.h). Specify hotSpotX and hotSpotY. + Load a Windows resource (as specified in the .rc file). + + + + + wxBITMAP_TYPE_ICO + + + + + Load a cursor from a .ico icon file (only if USE_RESOURCE_LOADING_IN_MSW + is enabled in setup.h). Specify hotSpotX and hotSpotY. @param cursorId - A stock cursor identifier. May be one of: + A stock cursor identifier. May be one of: + + + + + + + + wxCURSOR_ARROW + + + + + A standard arrow cursor. + + + + + + wxCURSOR_RIGHT_ARROW + + + + + A standard arrow cursor + pointing to the right. + + + + + + wxCURSOR_BLANK + + + + + Transparent cursor. + + + + + + wxCURSOR_BULLSEYE + + + + + Bullseye cursor. + + + + + + wxCURSOR_CHAR + + + + + Rectangular character cursor. + + + + + + wxCURSOR_CROSS + + + + + A cross cursor. + + + + + + wxCURSOR_HAND + + + + + A hand cursor. + + - wxCURSOR_ARROW + wxCURSOR_IBEAM - A standard arrow cursor. - wxCURSOR_RIGHT_ARROW - A standard arrow cursor - pointing to the right. + An I-beam cursor (vertical line). - wxCURSOR_BLANK - Transparent cursor. - wxCURSOR_BULLSEYE + wxCURSOR_LEFT_BUTTON - Bullseye cursor. - wxCURSOR_CHAR - Rectangular character cursor. + Represents a mouse with the left button depressed. - wxCURSOR_CROSS - A cross cursor. - wxCURSOR_HAND + wxCURSOR_MAGNIFIER - A hand cursor. - wxCURSOR_IBEAM - An I-beam cursor (vertical line). + A magnifier icon. - wxCURSOR_LEFT_BUTTON - Represents a mouse with the left button depressed. - wxCURSOR_MAGNIFIER + wxCURSOR_MIDDLE_BUTTON - A magnifier icon. - wxCURSOR_MIDDLE_BUTTON - Represents a mouse with the middle button depressed. + Represents a mouse with the middle button depressed. - wxCURSOR_NO_ENTRY - A no-entry sign cursor. - wxCURSOR_PAINT_BRUSH + wxCURSOR_NO_ENTRY - A paintbrush cursor. - wxCURSOR_PENCIL - A pencil cursor. + A no-entry sign cursor. - wxCURSOR_POINT_LEFT - A cursor that points left. - wxCURSOR_POINT_RIGHT + wxCURSOR_PAINT_BRUSH - A cursor that points right. - wxCURSOR_QUESTION_ARROW - An arrow and question mark. + A paintbrush cursor. - wxCURSOR_RIGHT_BUTTON - Represents a mouse with the right button depressed. - wxCURSOR_SIZENESW + wxCURSOR_PENCIL - A sizing cursor pointing NE-SW. - wxCURSOR_SIZENS - A sizing cursor pointing N-S. + A pencil cursor. - wxCURSOR_SIZENWSE - A sizing cursor pointing NW-SE. - wxCURSOR_SIZEWE + wxCURSOR_POINT_LEFT - A sizing cursor pointing W-E. - wxCURSOR_SIZING - A general sizing cursor. + A cursor that points left. - wxCURSOR_SPRAYCAN - A spraycan cursor. - wxCURSOR_WAIT + wxCURSOR_POINT_RIGHT - A wait cursor. - wxCURSOR_WATCH - A watch cursor. + A cursor that points right. - wxCURSOR_ARROWWAIT - A cursor with both an arrow and - an hourglass, (windows.) - Note that not all cursors are available on all platforms. + wxCURSOR_QUESTION_ARROW + + + + + An arrow and question mark. + + + + + + wxCURSOR_RIGHT_BUTTON + + + + + Represents a mouse with the right button depressed. + + + + + + wxCURSOR_SIZENESW + + + + + A sizing cursor pointing NE-SW. + + + + + + wxCURSOR_SIZENS + + + + + A sizing cursor pointing N-S. + + + + + + wxCURSOR_SIZENWSE + + + + + A sizing cursor pointing NW-SE. + + + + + + wxCURSOR_SIZEWE + + + + + A sizing cursor pointing W-E. + + + + + + wxCURSOR_SIZING + + + + + A general sizing cursor. + + + + + + wxCURSOR_SPRAYCAN + + + + + A spraycan cursor. + + + + + + wxCURSOR_WAIT + + + + + A wait cursor. + + + + + + wxCURSOR_WATCH + + + + + A watch cursor. + + + + + + wxCURSOR_ARROWWAIT + + + + + A cursor with both an arrow and + an hourglass, (windows.) + + + + + + Note that not all cursors are available on all platforms. @param cursor - Pointer or reference to a cursor to copy. + Pointer or reference to a cursor to copy. */ wxCursor(); wxCursor(const char bits[], int width, int height, - int hotSpotX=-1, int hotSpotY=-1, - const char maskBits[]=@NULL, - wxColour* fg=@NULL, - wxColour* bg=@NULL); + int hotSpotX = -1, int hotSpotY = -1, + const char maskBits[] = NULL, + wxColour* fg = NULL, + wxColour* bg = NULL); wxCursor(const wxString& cursorName, long type, - int hotSpotX=0, int hotSpotY=0); + int hotSpotX = 0, int hotSpotY = 0); wxCursor(int cursorId); wxCursor(const wxImage& image); wxCursor(const wxCursor& cursor); @@ -262,7 +450,6 @@ public: Destroys the cursor. See @ref overview_refcountdestruct "reference-counted object destruction" for more info. - A cursor can be reused for more than one window, and does not get destroyed when the window is destroyed. wxWidgets destroys all cursors on application exit, although @@ -273,7 +460,7 @@ public: /** Returns @true if cursor data is present. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** Assignment operator, using @ref overview_trefcount "reference counting". diff --git a/interface/dataobj.h b/interface/dataobj.h index c358ffa28d..2256b1f124 100644 --- a/interface/dataobj.h +++ b/interface/dataobj.h @@ -37,7 +37,7 @@ class wxCustomDataObject : public wxDataObjectSimple { public: /** - The constructor accepts a @e format argument which specifies the (single) + The constructor accepts a @a format argument which specifies the (single) format supported by this object. If it isn't set here, wxDataObjectSimple::SetFormat should be used. */ @@ -54,10 +54,10 @@ public: ~wxCustomDataObject(); /** - This function is called to allocate @e size bytes of memory from SetData(). + This function is called to allocate @a size bytes of memory from SetData(). The default version just uses the operator new. */ - virtual void * Alloc(size_t size); + virtual void* Alloc(size_t size); /** This function is called when the data is freed, you may override it to anything @@ -69,7 +69,7 @@ public: /** Returns a pointer to the data. */ - virtual void * GetData(); + virtual void* GetData(); /** Returns the data size in bytes. @@ -84,7 +84,6 @@ public: /** Like SetData(), but doesn't copy the data - instead the object takes ownership of the pointer. - @b wxPython note: This method expects a string in wxPython. You can pass nearly any object by pickling it first. */ @@ -125,10 +124,10 @@ public: wxDataObjectComposite(); /** - Adds the @e dataObject to the list of supported objects and it becomes the - preferred object if @e preferred is @true. + Adds the @a dataObject to the list of supported objects and it becomes the + preferred object if @a preferred is @true. */ -#define void Add(wxDataObjectSimple dataObject, bool preferred = @false) /* implementation is private */ + void Add(wxDataObjectSimple dataObject, bool preferred = false); /** Report the format passed to the SetData method. This should be the @@ -197,7 +196,6 @@ public: /** Copy the data from the buffer, return @true on success. Must be implemented in the derived class if the object supports setting its data. - @b wxPython note: When implementing this method in wxPython, the data comes as a single string parameter rather than the two shown here. */ @@ -401,7 +399,7 @@ class wxURLDataObject { public: /** - Constructor, may be used to initialize the URL. If @e url is empty, + Constructor, may be used to initialize the URL. If @a url is empty, SetURL() can be used later. */ wxURLDataObject(const wxString& url = wxEmptyString); @@ -409,12 +407,12 @@ public: /** Returns the URL stored by this object, as a string. */ -#define wxString GetURL() /* implementation is private */ + wxString GetURL(); /** Sets the URL stored by this object. */ -#define void SetURL(const wxString& url) /* implementation is private */ + void SetURL(const wxString& url); }; @@ -563,11 +561,11 @@ public: Copy all supported formats in the given direction to the array pointed to by @e formats. There is enough space for GetFormatCount(dir) formats in it. */ - virtual void GetAllFormats(wxDataFormat * formats, + virtual void GetAllFormats(wxDataFormat* formats, Direction dir = Get); /** - The method will write the data of the format @e format in the buffer @e buf and + The method will write the data of the format @a format in the buffer @a buf and return @true on success, @false on failure. */ virtual bool GetDataHere(const wxDataFormat& format, void buf); @@ -583,16 +581,15 @@ public: virtual size_t GetFormatCount(Direction dir = Get); /** - Returns the preferred format for either rendering the data (if @e dir is @c Get, + Returns the preferred format for either rendering the data (if @a dir is @c Get, its default value) or for setting it. Usually this will be the native format of the wxDataObject. */ virtual wxDataFormat GetPreferredFormat(Direction dir = Get); /** - Set the data in the format @e format of the length @e len provided in the + Set the data in the format @a format of the length @a len provided in the buffer @e buf. - Returns @true on success, @false on failure. */ virtual bool SetData(const wxDataFormat& format, size_t len, diff --git a/interface/dataview.h b/interface/dataview.h index 0f0b1f82e0..cdc7491ef4 100644 --- a/interface/dataview.h +++ b/interface/dataview.h @@ -68,7 +68,7 @@ public: /** */ - wxDataViewEvent(wxEventType commandType = wxEVT_@NULL, + wxDataViewEvent(wxEventType commandType = wxEVT_NULL, int winid = 0); wxDataViewEvent(const wxDataViewEvent& event); //@} @@ -198,7 +198,6 @@ public: Oberride this to indicate that the row has special font attributes. This only affects the wxDataViewTextRendererText renderer. - See also wxDataViewItemAttr. */ bool GetAttr(unsigned int row, unsigned int col, @@ -387,7 +386,6 @@ public: The compare function to be used by control. The default compare function sorts by container and other items separately and in ascending order. Override this for a different sorting behaviour. - See also HasDefaultCompare(). */ virtual int Compare(const wxDataViewItem& item1, @@ -399,7 +397,6 @@ public: Oberride this to indicate that the item has special font attributes. This only affects the wxDataViewTextRendererText renderer. - See also wxDataViewItemAttr. */ bool GetAttr(const wxDataViewItem& item, unsigned int col, @@ -426,7 +423,7 @@ public: /** Override this to indicate which wxDataViewItem representing the parent - of @e item or an invalid wxDataViewItem if the the root item is + of @a item or an invalid wxDataViewItem if the the root item is the parent item. */ virtual wxDataViewItem GetParent(const wxDataViewItem& item); @@ -459,7 +456,7 @@ public: virtual bool HasDefaultCompare(); /** - Override this to indicate of @e item is a container, i.e. if + Override this to indicate of @a item is a container, i.e. if it can have child items. */ virtual bool IsContainer(const wxDataViewItem& item); @@ -473,7 +470,6 @@ public: /** Call this to inform the model that an item has changed. - This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED event (in which the column fields will not be set) to the user. */ @@ -494,7 +490,6 @@ public: /** Call this to inform the model that several items have changed. - This will eventually emit wxEVT_DATAVIEW_ITEM_VALUE_CHANGED events (in which the column fields will not be set) to the user. */ @@ -507,7 +502,7 @@ public: const wxDataViewItemArray& items); /** - Remove the @e notifier from the list of notifiers. + Remove the @a notifier from the list of notifiers. */ void RemoveNotifier(wxDataViewModelNotifier* notifier); @@ -533,7 +528,6 @@ public: been changed. This is also called from wxDataViewCtrl's internal editing code, e.g. when editing a text field in the control. - This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED event to the user. */ @@ -573,7 +567,7 @@ public: */ wxDataViewCustomRenderer(const wxString& varianttype = "string", wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, - bool no_init = @false); + bool no_init = false); /** Destructor. @@ -589,18 +583,18 @@ public: /** Override this to create the actual editor control once editing - is about to start. @e parent is the parent of the editor - control, @e labelRect indicates the position and - size of the editor control and @e value is its initial value: + is about to start. @a parent is the parent of the editor + control, @a labelRect indicates the position and + size of the editor control and @a value is its initial value: */ - virtual wxControl* CreateEditorCtrl(wxWindow * parent, + virtual wxControl* CreateEditorCtrl(wxWindow* parent, wxRect labelRect, - const wxVariant & value); + const wxVariant& value); /** Create DC on request. Internal. */ -#define virtual wxDC* GetDC() /* implementation is private */ + virtual wxDC* GetDC(); /** Return size required to show content. @@ -612,7 +606,7 @@ public: from the editor control (pointed to by @e editor): */ virtual bool GetValueFromEditorCtrl(wxControl* editor, - wxVariant & value); + wxVariant& value); /** Override this and make it return @e @true in order to @@ -753,19 +747,19 @@ public: /** */ - wxDataViewItem(void* id = @NULL); + wxDataViewItem(void* id = NULL); wxDataViewItem(const wxDataViewItem& item); //@} /** Returns the ID. */ -#define void* GetID() /* implementation is private */ + void* GetID(); /** Returns @true if the ID is not @e @NULL. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); }; @@ -863,7 +857,6 @@ public: /** Add a wxDataViewColumn to the control. Returns @e @true on success. - Note that there is a number of short cut methods which implicitly create a wxDataViewColumn and a wxDataViewRenderer for it (see below). @@ -986,7 +979,7 @@ public: /** Collapses the item. */ - void Collapse(const wxDataViewItem & item); + void Collapse(const wxDataViewItem& item); /** Create the control. Useful for two step creation. @@ -1005,16 +998,16 @@ public: /** Call this to ensure that the given item is visible. */ - void EnsureVisible(const wxDataViewItem & item, - const wxDataViewColumn* column = @NULL); + void EnsureVisible(const wxDataViewItem& item, + const wxDataViewColumn* column = NULL); /** Expands the item. */ - void Expand(const wxDataViewItem & item); + void Expand(const wxDataViewItem& item); /** - Returns pointer to the column. @e pos refers to the + Returns pointer to the column. @a pos refers to the position in the control which may change after reordering columns by the user. */ @@ -1033,7 +1026,7 @@ public: /** Returns column containing the expanders. */ - wxDataViewColumn * GetExpanderColumn(); + wxDataViewColumn* GetExpanderColumn(); /** Returns indentation. @@ -1044,7 +1037,7 @@ public: Returns item rect. */ wxRect GetItemRect(const wxDataViewItem& item, - const wxDataViewColumn * col = @NULL); + const wxDataViewColumn* col = NULL); /** Returns pointer to the data model associated with the @@ -1058,10 +1051,10 @@ public: wxDataViewItem GetSelection(); /** - Fills @e sel with currently selected items and returns + Fills @a sel with currently selected items and returns their number. */ - int GetSelections(wxDataViewItemArray & sel); + int GetSelections(wxDataViewItemArray& sel); /** Returns the wxDataViewColumn currently responsible for sorting @@ -1073,17 +1066,17 @@ public: Hittest. */ void HitTest(const wxPoint& point, wxDataViewItem& item, - wxDataViewColumn *& col); + wxDataViewColumn*& col); /** Return @true if the item is selected. */ - bool IsSelected(const wxDataViewItem & item); + bool IsSelected(const wxDataViewItem& item); /** Select the given item. */ - void Select(const wxDataViewItem & item); + void Select(const wxDataViewItem& item); /** Select all items. @@ -1093,7 +1086,7 @@ public: /** Set which column shall contain the tree-like expanders. */ - void SetExpanderColumn(wxDataViewColumn * col); + void SetExpanderColumn(wxDataViewColumn* col); /** Sets the indendation. @@ -1103,12 +1096,12 @@ public: /** Sets the selection to the array of wxDataViewItems. */ - void SetSelections(const wxDataViewItemArray & sel); + void SetSelections(const wxDataViewItemArray& sel); /** Unselect the given item. */ - void Unselect(const wxDataViewItem & item); + void Unselect(const wxDataViewItem& item); /** Unselect all item. This method only has effect if multiple @@ -1314,7 +1307,6 @@ public: a certain aspect (e.g. max number of characters or only alphanumeric input, ASCII only etc.). Return @e @false if the value is not valid. - Please note that due to implementation limitations, this validation is done after the editing control already is destroyed and the editing process finished. @@ -1380,7 +1372,7 @@ class wxDataViewSpinRenderer : public wxDataViewCustomRenderer { public: /** - Constructor. @e min and @e max indicate the minimum und + Constructor. @a min and @a max indicate the minimum und maximum values of for the wxSpinCtrl. */ wxDataViewSpinRenderer(int min, int max, @@ -1451,7 +1443,7 @@ public: const wxString& text, int icon = -1, int expanded = -1, - wxClientData* data = @NULL); + wxClientData* data = NULL); /** @@ -1459,7 +1451,7 @@ public: wxDataViewItem AppendItem(const wxDataViewItem& parent, const wxString& text, int icon = -1, - wxClientData* data = @NULL); + wxClientData* data = NULL); /** Creates the control and a wxDataViewTreeStore as @@ -1539,7 +1531,7 @@ public: const wxString& text, int icon = -1, int expanded = -1, - wxClientData* data = @NULL); + wxClientData* data = NULL); /** Calls the same method from wxDataViewTreeStore but uess @@ -1549,7 +1541,7 @@ public: const wxDataViewItem& previous, const wxString& text, int icon = -1, - wxClientData* data = @NULL); + wxClientData* data = NULL); /** Calls the same method from wxDataViewTreeStore but uess @@ -1559,7 +1551,7 @@ public: const wxString& text, int icon = -1, int expanded = -1, - wxClientData* data = @NULL); + wxClientData* data = NULL); /** Calls the same method from wxDataViewTreeStore but uess @@ -1568,7 +1560,7 @@ public: wxDataViewItem PrependItem(const wxDataViewItem& parent, const wxString& text, int icon = -1, - wxClientData* data = @NULL); + wxClientData* data = NULL); /** Sets the image list. @@ -1633,7 +1625,7 @@ public: const wxString& text, const wxIcon& icon = wxNullIcon, const wxIcon& expanded = wxNullIcon, - wxClientData* data = @NULL); + wxClientData* data = NULL); /** Append an item. @@ -1641,7 +1633,7 @@ public: wxDataViewItem AppendItem(const wxDataViewItem& parent, const wxString& text, const wxIcon& icon = wxNullIcon, - wxClientData* data = @NULL); + wxClientData* data = NULL); /** Delete all item in the model. @@ -1697,7 +1689,7 @@ public: const wxString& text, const wxIcon& icon = wxNullIcon, const wxIcon& expanded = wxNullIcon, - wxClientData* data = @NULL); + wxClientData* data = NULL); /** Inserts an item after @e previous. @@ -1706,7 +1698,7 @@ public: const wxDataViewItem& previous, const wxString& text, const wxIcon& icon = wxNullIcon, - wxClientData* data = @NULL); + wxClientData* data = NULL); /** Inserts a container before the first child item or @e parent. @@ -1715,7 +1707,7 @@ public: const wxString& text, const wxIcon& icon = wxNullIcon, const wxIcon& expanded = wxNullIcon, - wxClientData* data = @NULL); + wxClientData* data = NULL); /** Inserts an item before the first child item or @e parent. @@ -1723,7 +1715,7 @@ public: wxDataViewItem PrependItem(const wxDataViewItem& parent, const wxString& text, const wxIcon& icon = wxNullIcon, - wxClientData* data = @NULL); + wxClientData* data = NULL); /** Sets the client data associated with the item. @@ -1847,7 +1839,6 @@ public: /** Returns the renderer of this wxDataViewColumn. - See also wxDataViewRenderer. */ wxDataViewRenderer* GetRenderer(); @@ -1859,7 +1850,6 @@ public: /** Returns @true if the column is sortable. - See SetSortable() */ bool GetSortable(); @@ -1871,7 +1861,6 @@ public: /** Returns @true, if the sort order is ascending. - See also SetSortOrder() */ bool IsSortOrderAscending(); @@ -1906,7 +1895,7 @@ public: make the column header clickable. Call SetSortOrder() afterwards to actually make the sort indicator appear. - If @e sortable is @false, the column header is + If @a sortable is @false, the column header is no longer clickable and the sort indicator (little arrow) will disappear. */ diff --git a/interface/datectrl.h b/interface/datectrl.h index 4d9b8e92b1..ecf23f98a4 100644 --- a/interface/datectrl.h +++ b/interface/datectrl.h @@ -43,7 +43,7 @@ @endStyleTable @beginEventTable - @event{EVT_DATE_CHANGED(id\, func)}: + @event{EVT_DATE_CHANGED(id, func)}: This event fires when the user changes the current selection in the control. @endEventTable @@ -62,7 +62,7 @@ public: Initializes the object and calls Create() with all the parameters. */ - wxDatePickerCtrl(wxWindow * parent, wxWindowID id, + wxDatePickerCtrl(wxWindow* parent, wxWindowID id, const wxDateTime& dt = wxDefaultDateTime, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, @@ -72,37 +72,30 @@ public: /** @param parent - Parent window, must not be non-@NULL. - + Parent window, must not be non-@NULL. @param id - The identifier for the control. - + The identifier for the control. @param dt - The initial value of the control, if an invalid date (such as the - default value) is used, the control is set to today. - + The initial value of the control, if an invalid date (such as the + default value) is used, the control is set to today. @param pos - Initial position. - + Initial position. @param size - Initial size. If left at default value, the control chooses its - own best size by using the height approximately equal to a text control and - width large enough to show the date string fully. - + Initial size. If left at default value, the control chooses its + own best size by using the height approximately equal to a text control and + width large enough to show the date string fully. @param style - The window style, should be left at 0 as there are no - special styles for this control in this version. - + The window style, should be left at 0 as there are no + special styles for this control in this version. @param validator - Validator which can be used for additional date checks. - + Validator which can be used for additional date checks. @param name - Control name. + Control name. @returns @true if the control was successfully created or @false if - creation failed. + creation failed. */ - bool Create(wxWindow * parent, wxWindowID id, + bool Create(wxWindow* parent, wxWindowID id, const wxDateTime& dt = wxDefaultDateTime, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, @@ -114,20 +107,19 @@ public: If the control had been previously limited to a range of dates using SetRange(), returns the lower and upper bounds of this range. If no range is set (or only one of the bounds is set), - @e dt1 and/or @e dt2 are set to be invalid. + @a dt1 and/or @a dt2 are set to be invalid. @param dt1 - Pointer to the object which receives the lower range limit or - becomes invalid if it is not set. May be @NULL if the caller is not - interested in lower limit - + Pointer to the object which receives the lower range limit or + becomes invalid if it is not set. May be @NULL if the caller is not + interested in lower limit @param dt2 - Same as above but for the upper limit + Same as above but for the upper limit @returns @false if no range limits are currently set, @true if at least one - bound is set. + bound is set. */ - bool GetRange(wxDateTime * dt1, wxDateTime dt2); + bool GetRange(wxDateTime* dt1, wxDateTime dt2); /** Returns the currently selected. If there is no selection or the selection is @@ -138,7 +130,6 @@ public: /** Please note that this function is only available in the generic version of this control. The native version always uses the current system locale. - Sets the display format for the date in the control. See wxDateTime for the meaning of format strings. @@ -147,19 +138,18 @@ public: void SetFormat(const wxChar* format); /** - Sets the valid range for the date selection. If @e dt1 is valid, it becomes - the earliest date (inclusive) accepted by the control. If @e dt2 is valid, + Sets the valid range for the date selection. If @a dt1 is valid, it becomes + the earliest date (inclusive) accepted by the control. If @a dt2 is valid, it becomes the latest possible date. @remarks If the current value of the control is outside of the newly set - range bounds, the behaviour is undefined. + range bounds, the behaviour is undefined. */ void SetRange(const wxDateTime& dt1, const wxDateTime& dt2); /** Changes the current value of the control. The date should be valid and included in the currently selected range, if any. - Calling this method does not result in a date change event. */ void SetValue(const wxDateTime& dt); diff --git a/interface/datetime.h b/interface/datetime.h index 1d37e5ae7c..a41d180d8f 100644 --- a/interface/datetime.h +++ b/interface/datetime.h @@ -35,7 +35,6 @@ public: Here are the trivial accessors. Other functions, which might have to perform some more complicated calculations to find the answer are under the @ref overview_datetimecalculations "Calendar calculations" section. - IsValid() GetTicks() @@ -89,7 +88,6 @@ public: @ref setjdn() JDN and you may also get its JDN, @ref getmodifiedjuliandaynumber() MJD or @ref getratadie() "Rata Die number" from it. - @ref wxdatetimejdn() "wxDateTime(double jdn)" @ref setjdn() "Set(double jdn)" @@ -110,10 +108,8 @@ public: The functions in this section perform the basic calendar calculations, mostly related to the week days. They allow to find the given week day in the week with given number (either in the month or in the year) and so on. - All (non-const) functions in this section don't modify the time part of the wxDateTime -- they only work with the date part of it. - SetToWeekDayInSameWeek() GetWeekDayInSameWeek() @@ -151,7 +147,6 @@ public: construct a date object from separate values for day, month and year, you should use IsValid() method to check that the values were correct as constructors can not return an error code. - @ref wxdatetimedef() wxDateTime @ref wxdatetimetimet() wxDateTime(time_t) @@ -205,7 +200,6 @@ public: positive or zero) to the year in BC/AD notation. For the positive years, nothing is done, but the year 0 is year 1 BC and so for other years there is a difference of 1. - This function should be used like this: */ static int ConvertYearToBC(int year); @@ -215,13 +209,11 @@ public: objects. As explained in the overview, either wxTimeSpan or wxDateSpan may be added to wxDateTime, hence all functions are overloaded to accept both arguments. - Also, both @c Add() and @c Subtract() have both const and non-const version. The first one returns a new object which represents the sum/difference of the original one with the argument while the second form modifies the object to which it is applied. The operators -= and += are defined to be equivalent to the second forms of these functions. - @ref addts() Add(wxTimeSpan) @ref addds() Add(wxDateSpan) @@ -245,7 +237,6 @@ public: /** There are several function to allow date comparison. To supplement them, a few global operators , etc taking wxDateTime are defined. - IsEqualTo() IsEarlierThan() @@ -266,15 +257,14 @@ public: /** This function does the same as the standard ANSI C @c strftime(3) function. - Please see its description for the meaning of @e format parameter. - + Please see its description for the meaning of @a format parameter. It also accepts a few wxWidgets-specific extensions: you can optionally specify the width of the field to follow using @c printf(3)-like syntax and the format specification @c %l can be used to get the number of milliseconds. - @sa ParseFormat() + @see ParseFormat() */ - wxString Format(const wxChar * format = wxDefaultDateTimeFormat, + wxString Format(const wxChar* format = wxDefaultDateTimeFormat, const TimeZone& tz = Local); /** @@ -285,13 +275,13 @@ public: /** Returns the combined date-time representation in the ISO 8601 format - (YYYY-MM-DDTHH:MM:SS). The @e sep parameter default value produces the + (YYYY-MM-DDTHH:MM:SS). The @a sep parameter default value produces the result exactly corresponding to the ISO standard, but it can also be useful to use a space as seprator if a more human-readable combined date-time representation is needed. - @sa FormatISODate(), FormatISOTime(), - ParseISOCombined() + @see FormatISODate(), FormatISOTime(), + ParseISOCombined() */ wxString FormatISOCombined(char sep = 'T'); @@ -314,20 +304,19 @@ public: wxString FormatTime(); /** - Transform the date from the given time zone to the local one. If @e noDST is + Transform the date from the given time zone to the local one. If @a noDST is @true, no DST adjustments will be made. - Returns the date in the local time zone. */ wxDateTime FromTimezone(const TimeZone& tz, - bool noDST = @false); + bool noDST = false); /** Returns the translations of the strings @c AM and @c PM used for time formatting for the current locale. Either of the pointers may be @NULL if the corresponding value is not needed. */ - static void GetAmPmStrings(wxString * am, wxString * pm); + static void GetAmPmStrings(wxString* am, wxString* pm); /** Returns the date and time in @@ -341,7 +330,7 @@ public: by default). This function suffers from limitations described in @ref overview_tdatedst "DST overview". - @sa GetEndDST() + @see GetEndDST() */ static wxDateTime GetBeginDST(int year = Inv_Year, Country country = Country_Default); @@ -355,7 +344,7 @@ public: Returns the current default country. The default country is used for DST calculations, for example. - @sa SetCountry() + @see SetCountry() */ static Country GetCountry(); @@ -372,10 +361,9 @@ public: /** Returns the object having the same date component as this one but time of 00:00:00. - This function is new since wxWidgets version 2.8.2 - @sa ResetTime() + @see ResetTime() */ wxDateTime GetDateOnly(); @@ -394,7 +382,7 @@ public: Returns the end of DST for the given country in the given year (current one by default). - @sa GetBeginDST() + @see GetBeginDST() */ static wxDateTime GetEndDST(int year = Inv_Year, Country country = Country_Default); @@ -407,13 +395,13 @@ public: /** Synonym for GetJulianDayNumber(). */ -#define double GetJDN() /* implementation is private */ + double GetJDN(); /** Returns the @ref setjdn() JDN corresponding to this date. Beware of rounding errors! - @sa GetModifiedJulianDayNumber() + @see GetModifiedJulianDayNumber() */ double GetJulianDayNumber(); @@ -435,7 +423,7 @@ public: /** Synonym for GetModifiedJulianDayNumber(). */ -#define double GetMJD() /* implementation is private */ + double GetMJD(); /** Returns the milliseconds in the given timezone (local one by default). @@ -464,7 +452,7 @@ public: Gets the full (default) or abbreviated (specify @c Name_Abbr name of the given month. - @sa GetWeekDayName() + @see GetWeekDayName() */ static wxString GetMonthName(Month month, NameFlags flags = Name_Full); @@ -479,8 +467,7 @@ public: /** Returns the number of days in the given year or in the given month of the year. - - The only supported value for @e cal parameter is currently @c Gregorian. + The only supported value for @a cal parameter is currently @c Gregorian. */ static wxDateTime_t GetNumberOfDays(int year, Calendar cal = Gregorian); @@ -497,7 +484,6 @@ public: /** Return the @e Rata Die number of this date. - By definition, the Rata Die number is a date specified as the number of days relative to a base date of December 31 of the year 0. Thus January 1 of the year 1 is Rata Die day 1. @@ -533,7 +519,7 @@ public: the flavour of function GetTmNow() taking a parameter. */ - static struct tm * GetTmNow(); + static struct tm* GetTmNow(); /** Returns the copy of this object to which @@ -555,14 +541,13 @@ public: Gets the full (default) or abbreviated (specify @c Name_Abbr name of the given week day. - @sa GetMonthName() + @see GetMonthName() */ static wxString GetWeekDayName(WeekDay weekday, NameFlags flags = Name_Full); /** Returns the ordinal number of the week in the month (in 1...5 range). - As GetWeekOfYear(), this function supports both conventions for the week start. See the description of these @ref overview_wxdatetime "week start" conventions. @@ -577,9 +562,8 @@ public: definitions are the same as saying that the first week of the year must contain more than half of its days in this year. Accordingly, the week number will always be in 1...53 range (52 for non-leap years). - The function depends on the @ref overview_wxdatetime "week start" convention - specified by the @e flags argument but its results for + specified by the @a flags argument but its results for @c Sunday_First are not well-defined as the ISO definition quoted above applies to the weeks starting on Monday only. */ @@ -601,14 +585,14 @@ public: Returns @true if IsStrictlyBetween() is @true or if the date is equal to one of the limit values. - @sa IsStrictlyBetween() + @see IsStrictlyBetween() */ bool IsBetween(const wxDateTime& t1, const wxDateTime& t2); /** Returns @true if the DST is applied for this date in the given country. */ -#define int IsDST(Country country = Country_Default) /* implementation is private */ + int IsDST(Country country = Country_Default); /** Returns @true if DST was used n the given year (the current one by @@ -647,8 +631,7 @@ public: bool IsLaterThan(const wxDateTime& datetime); /** - Returns @true if the @e year is a leap one in the specified calendar. - + Returns @true if the @a year is a leap one in the specified calendar. This functions supports Gregorian and Julian calendars. */ static bool IsLeapYear(int year = Inv_Year, @@ -667,7 +650,7 @@ public: /** Returns @true if this date lies strictly between the two others, - @sa IsBetween() + @see IsBetween() */ bool IsStrictlyBetween(const wxDateTime& t1, const wxDateTime& t2); @@ -694,32 +677,32 @@ public: in place. */ wxDateTime MakeFromTimezone(const TimeZone& tz, - bool noDST = @false); + bool noDST = false); /** Modifies the object in place to represent the date in another time zone. If - @e noDST is @true, no DST adjustments will be made. + @a noDST is @true, no DST adjustments will be made. */ wxDateTime MakeTimezone(const TimeZone& tz, - bool noDST = @false); + bool noDST = false); /** This is the same as calling MakeTimezone() with the argument @c GMT0. */ - wxDateTime MakeUTC(bool noDST = @false); + wxDateTime MakeUTC(bool noDST = false); /** Returns the object corresponding to the current time. - Example: + Note that this function is accurate up to second: UNow() should be used for better precision (but it is less efficient and might not be available on all platforms). - @sa Today() + @see Today() */ -#define static wxDateTime Now() /* implementation is private */ + static wxDateTime Now(); //@{ /** @@ -727,72 +710,66 @@ public: only allows the date to be specified. It is thus less flexible then ParseDateTime(), but also has less chances to misinterpret the user input. - Returns @NULL if the conversion failed, otherwise return the pointer to the character which stopped the scan. */ - const char * ParseDate(const wxString& date, - wxString::const_iterator * end = @NULL); - const char * ParseDate(const char * date); - const wchar_t * ParseDate(const wchar_t * date); + const char* ParseDate(const wxString& date, + wxString::const_iterator* end = NULL); + const char* ParseDate(const char* date); + const wchar_t* ParseDate(const wchar_t* date); //@} //@{ /** - Parses the string @e datetime containing the date and time in free format. + Parses the string @a datetime containing the date and time in free format. This function tries as hard as it can to interpret the given string as date and time. Unlike wxDateTime::ParseRfc822Date, it will accept anything that may be accepted and will only reject strings which can not be parsed in any way at all. - Returns @NULL if the conversion failed, otherwise return the pointer to the character which stopped the scan. */ - const char * ParseDateTime(const wxString& datetime, - wxString::const_iterator * end = @NULL); - const char * ParseDateTime(const char * datetime); - const wchar_t * ParseDateTime(const wchar_t * datetime); + const char* ParseDateTime(const wxString& datetime, + wxString::const_iterator* end = NULL); + const char* ParseDateTime(const char* datetime); + const wchar_t* ParseDateTime(const wchar_t* datetime); //@} //@{ /** - This function parses the string @e date according to the given + This function parses the string @a date according to the given @e format. The system @c strptime(3) function is used whenever available, but even if it is not, this function is still implemented, although support for locale-dependent format specifiers such as @c "%c", @c "%x" or @c "%X" may not be perfect and GNU extensions such as @c "%z" and @c "%Z" are not implemented. This function does handle the month and weekday names in the current locale on all platforms, however. - Please see the description of the ANSI C function @c strftime(3) for the syntax of the format string. - - The @e dateDef parameter is used to fill in the fields which could not be + The @a dateDef parameter is used to fill in the fields which could not be determined from the format string. For example, if the format is @c "%d" (the ay of the month), the month and the year are taken from @e dateDef. If it is not specified, Today() is used as the default date. - Returns @NULL if the conversion failed, otherwise return the pointer to the character which stopped the scan. */ - const char * ParseFormat(const wxString& date, - const wxString& format = wxDefaultDateTimeFormat, - const wxDateTime& dateDef = wxDefaultDateTime, - wxString::const_iterator * end = @NULL); - const char * ParseFormat(const char * date, - const wxString& format = wxDefaultDateTimeFormat, - const wxDateTime& dateDef = wxDefaultDateTime); - const wchar_t * ParseFormat(const wchar_t * date, - const wxString& format = wxDefaultDateTimeFormat, - const wxDateTime& dateDef = wxDefaultDateTime); + const char* ParseFormat(const wxString& date, + const wxString& format = wxDefaultDateTimeFormat, + const wxDateTime& dateDef = wxDefaultDateTime, + wxString::const_iterator* end = NULL); + const char* ParseFormat(const char* date, + const wxString& format = wxDefaultDateTimeFormat, + const wxDateTime& dateDef = wxDefaultDateTime); + const wchar_t* ParseFormat(const wchar_t* date, + const wxString& format = wxDefaultDateTimeFormat, + const wxDateTime& dateDef = wxDefaultDateTime); //@} /** This function parses the string containing the date and time in ISO 8601 combined format (YYYY-MM-DDTHH:MM:SS). The separator between the date and time - parts must be equal to @e sep for the function to succeed. - + parts must be equal to @a sep for the function to succeed. Returns @true if the entire string was parsed successfully, @false otherwise. */ @@ -800,7 +777,6 @@ public: /** This function parses the date in ISO 8601 format (YYYY-MM-DD). - Returns @true if the entire string was parsed successfully, @false otherwise. */ @@ -808,7 +784,6 @@ public: /** This function parses the time in ISO 8601 format (HH:MM:SS). - Returns @true if the entire string was parsed successfully, @false otherwise. */ @@ -816,40 +791,37 @@ public: //@{ /** - Parses the string @e date looking for a date formatted according to the RFC + Parses the string @a date looking for a date formatted according to the RFC 822 in it. The exact description of this format may, of course, be found in the RFC (section 5), but, briefly, this is the format used in the headers of Internet email messages and one of the most common strings expressing date in this format may be something like @c "Sat, 18 Dec 1999 00:48:30 +0100". - Returns @NULL if the conversion failed, otherwise return the pointer to the character immediately following the part of the string which could be parsed. If the entire string contains only the date in RFC 822 format, the returned pointer will be pointing to a @c NUL character. - This function is intentionally strict, it will return an error for any string which is not RFC 822 compliant. If you need to parse date formatted in more free ways, you should use ParseDateTime() or ParseDate() instead. */ - const char * ParseRfc822Date(const wxString& date, - wxString::const_iterator * end = @NULL); - const char * ParseRfc822Date(const char* date); - const wchar_t * ParseRfc822Date(const wchar_t* date); + const char* ParseRfc822Date(const wxString& date, + wxString::const_iterator* end = NULL); + const char* ParseRfc822Date(const char* date); + const wchar_t* ParseRfc822Date(const wchar_t* date); //@} //@{ /** This functions is like ParseDateTime(), but only allows the time to be specified in the input string. - Returns @NULL if the conversion failed, otherwise return the pointer to the character which stopped the scan. */ - const char * ParseTime(const wxString& time, - wxString::const_iterator * end = @NULL); - const char * ParseTime(const char * time); - const wchar_t * ParseTime(const wchar_t * time); + const char* ParseTime(const wxString& time, + wxString::const_iterator* end = NULL); + const char* ParseTime(const char* time); + const wchar_t* ParseTime(const wchar_t* time); //@} /** @@ -863,7 +835,6 @@ public: FormatISOTime() and wxDateTime::FormatISOCombined) or by specifying any format at all and using Format() directly. - The conversions from text are more interesting, as there are much more possibilities to care about. The simplest cases can be taken care of with ParseFormat() which can parse any date in the @@ -872,7 +843,6 @@ public: which (still...) defines the format of email messages on the Internet. This format can not be described with @c strptime(3)-like format strings used by Format(), hence the need for a separate function. - But the most interesting functions are ParseTime(), ParseDate() and @@ -883,7 +853,6 @@ public: format. As an example, ParseDateTime() can parse the strings such as @c "tomorrow", @c "March first" and even @c "next Sunday". - Finally notice that each of the parsing functions is available in several overloads: if the input string is a narrow (@c char *) string, then a narrow pointer is returned. If the input string is a wide string, a wide char @@ -891,7 +860,6 @@ public: char pointer is also returned for backwards compatibility but there is also an additional argument of wxString::const_iterator type in which, if it is not @NULL, an iterator pointing to the end of the scanned string part is returned. - ParseFormat() ParseDateTime() @@ -930,21 +898,20 @@ public: /** Sets the date and time from the parameters. */ -#define wxDateTime Set(wxDateTime_t day, Month month = Inv_Month, - int year = Inv_Year, - wxDateTime_t hour = 0, - wxDateTime_t minute = 0, - wxDateTime_t second = 0, - wxDateTime_t millisec = 0) /* implementation is private */ + wxDateTime Set(wxDateTime_t day, Month month = Inv_Month, + int year = Inv_Year, + wxDateTime_t hour = 0, + wxDateTime_t minute = 0, + wxDateTime_t second = 0, + wxDateTime_t millisec = 0); /** Sets the country to use by default. This setting influences the DST calculations, date formatting and other things. - - The possible values for @e country parameter are enumerated in + The possible values for @a country parameter are enumerated in @ref overview_wxdatetime "wxDateTime constants section". - @sa GetCountry() + @see GetCountry() */ static void SetCountry(Country country); @@ -994,7 +961,6 @@ public: /** Sets the date to the last day in the specified month (the current one by default). - Returns the reference to the modified object itself. */ wxDateTime SetToLastMonthDay(Month month = Inv_Month, @@ -1003,59 +969,52 @@ public: /** The effect of calling this function is the same as of calling @c SetToWeekDay(-1, weekday, month, year). The date will be set to the last - @e weekday in the given month and year (the current ones by default). - + @a weekday in the given month and year (the current ones by default). Always returns @true. */ bool SetToLastWeekDay(WeekDay weekday, Month month = Inv_Month, int year = Inv_Year); /** - Sets the date so that it will be the first @e weekday following the current + Sets the date so that it will be the first @a weekday following the current date. - Returns the reference to the modified object itself. */ wxDateTime SetToNextWeekDay(WeekDay weekday); /** - Sets the date so that it will be the last @e weekday before the current + Sets the date so that it will be the last @a weekday before the current date. - Returns the reference to the modified object itself. */ wxDateTime SetToPrevWeekDay(WeekDay weekday); /** - Sets the date to the @e n-th @e weekday in the given month of the given + Sets the date to the @e n-th @a weekday in the given month of the given year (the current month and year are used by default). The parameter @e n may be either positive (counting from the beginning of the month) or negative (counting from the end of it). - For example, @c SetToWeekDay(2, wxDateTime::Wed) will set the date to the second Wednesday in the current month and @c SetToWeekDay(-1, wxDateTime::Sun) -- to the last Sunday in it. - Returns @true if the date was modified successfully, @false otherwise meaning that the specified date doesn't exist. */ bool SetToWeekDay(WeekDay weekday, int n = 1, Month month = Inv_Month, - int year = Inv_Year); + int year = Inv_Year); /** Adjusts the date so that it will still lie in the same week as before, but its week day will be the given one. - Returns the reference to the modified object itself. */ wxDateTime SetToWeekDayInSameWeek(WeekDay weekday, WeekFlags flags = Monday_First); /** - Set the date to the given @e weekday in the week number @e numWeek of the - given @e year . The number should be in range 1...53. - + Set the date to the given @a weekday in the week number @a numWeek of the + given @a year . The number should be in range 1...53. Note that the returned date may be in a different year than the one passed to this function because both the week 1 and week 52 or 53 (for leap years) contain days from different years. See @@ -1066,11 +1025,10 @@ public: WeekDay weekday = Mon); /** - Sets the date to the day number @e yday in the same year (i.e., unlike the + Sets the date to the day number @a yday in the same year (i.e., unlike the other functions, this one does not use the current year). The day number should be in the range 1...366 for the leap years and 1...365 for the other ones. - Returns the reference to the modified object itself. */ wxDateTime SetToYearDay(wxDateTime_t yday); @@ -1085,10 +1043,10 @@ public: either set or return the static variables of wxDateSpan (the country), return the current moment, year, month or number of days in it, or do some general calendar-related actions. - Please note that although several function accept an extra @e Calendar parameter, it is currently ignored as only the Gregorian calendar is supported. Future versions will support other calendars. + SetCountry() GetCountry() @@ -1138,7 +1096,6 @@ public: /** Please see the @ref overview_tdatetimezones "time zone overview" for more information about time zones. Normally, these functions should be rarely used. - FromTimezone() ToTimezone() @@ -1160,24 +1117,23 @@ public: /** - Transform the date to the given time zone. If @e noDST is @true, no + Transform the date to the given time zone. If @a noDST is @true, no DST adjustments will be made. - Returns the date in the new time zone. */ - wxDateTime ToTimezone(const TimeZone& tz, bool noDST = @false); + wxDateTime ToTimezone(const TimeZone& tz, bool noDST = false); /** This is the same as calling ToTimezone() with the argument @c GMT0. */ -#define wxDateTime ToUTC(bool noDST = @false) /* implementation is private */ + wxDateTime ToUTC(bool noDST = false); /** Returns the object corresponding to the midnight of the current day (i.e. the same as Now(), but the time part is set to 0). - @sa Now() + @see Now() */ static wxDateTime Today(); @@ -1186,15 +1142,15 @@ public: milliseconds if a function to get time with such precision is available on the current platform (supported under most Unices and Win32). - @sa Now() + @see Now() */ -#define static wxDateTime UNow() /* implementation is private */ + static wxDateTime UNow(); /** Same as @ref settm() Set. */ wxDateTime operator(const struct tm& tm); - }; +}; /** @@ -1280,14 +1236,14 @@ public: /** Returns a date span object corresponding to one day. - @sa Days() + @see Days() */ -#define static wxDateSpan Day() /* implementation is private */ + static wxDateSpan Day(); /** Returns a date span object corresponding to the given number of days. - @sa Day() + @see Day() */ static wxDateSpan Days(int days); @@ -1295,7 +1251,7 @@ public: Returns the number of days (only, that it not counting the weeks component!) in this date span. - @sa GetTotalDays() + @see GetTotalDays() */ int GetDays(); @@ -1308,14 +1264,14 @@ public: Returns the combined number of days in this date span, counting both weeks and days. It still doesn't take neither months nor years into the account. - @sa GetWeeks(), GetDays() + @see GetWeeks(), GetDays() */ int GetTotalDays(); /** Returns the number of weeks in this date span. - @sa GetTotalDays() + @see GetTotalDays() */ int GetWeeks(); @@ -1327,14 +1283,14 @@ public: /** Returns a date span object corresponding to one month. - @sa Months() + @see Months() */ static wxDateSpan Month(); /** Returns a date span object corresponding to the given number of months. - @sa Month() + @see Month() */ static wxDateSpan Months(int mon); @@ -1342,7 +1298,6 @@ public: /** Returns the product of the date span by the specified @e factor. The product is computed by multiplying each of the components by the factor. - The first version returns a new object, the second and third ones modify this object in place. */ @@ -1355,7 +1310,7 @@ public: /** Changes the sign of this date span. - @sa Negate() + @see Negate() */ wxDateSpan Neg(); wxDateSpan operator-(); @@ -1364,7 +1319,7 @@ public: /** Returns the date span with the opposite sign. - @sa Neg() + @see Neg() */ wxDateSpan Negate(); @@ -1405,28 +1360,28 @@ public: /** Returns a date span object corresponding to one week. - @sa Weeks() + @see Weeks() */ static wxDateSpan Week(); /** Returns a date span object corresponding to the given number of weeks. - @sa Week() + @see Week() */ static wxDateSpan Weeks(int weeks); /** Returns a date span object corresponding to one year. - @sa Years() + @see Years() */ static wxDateSpan Year(); /** Returns a date span object corresponding to the given number of years. - @sa Year() + @see Year() */ static wxDateSpan Years(int years); @@ -1473,7 +1428,7 @@ public: Returns the absolute value of the timespan: does not modify the object. */ -#define wxTimeSpan Abs() /* implementation is private */ + wxTimeSpan Abs(); /** GetSeconds() @@ -1507,7 +1462,7 @@ public: /** Returns the timespan for one day. */ -#define static wxTimespan Day() /* implementation is private */ + static wxTimespan Day(); /** Returns the timespan for the given number of days. @@ -1520,37 +1475,30 @@ public: H - number of @b Hours M - number of @b Minutes S - number of @b Seconds l - number of mi@b lliseconds D - number of @b Days E - number of w@b Eeks % - the percent character Note that, for example, the number of hours in the description above is not @@ -1558,15 +1506,13 @@ public: time span of 50 hours this would be 50) or just the hour part of the time span, which would be 2 in this case as 50 hours is equal to 2 days and 2 hours. - wxTimeSpan resolves this ambiguity in the following way: if there had been, indeed, the @c %D format specified preceding the @c %H, then it is interpreted as 2. Otherwise, it is 50. - The same applies to all other format specifiers: if they follow a specifier of larger unit, only the rest part is taken, otherwise the full value is used. */ - wxString Format(const wxChar * format = wxDefaultTimeSpanFormat); + wxString Format(const wxChar* format = wxDefaultTimeSpanFormat); /** Format() diff --git a/interface/datstrm.h b/interface/datstrm.h index 3d4f17d981..3f6a8ead37 100644 --- a/interface/datstrm.h +++ b/interface/datstrm.h @@ -32,20 +32,18 @@ public: //@{ /** ) - Constructs a datastream object from an output stream. Only write methods will be available. The second form is only available in Unicode build of wxWidgets. @param stream - The output stream. - + The output stream. @param conv - Charset conversion object object used to encoding Unicode - strings before writing them to the stream - in Unicode mode (see WriteString() - documentation for detailed description). Note that you must not destroy - conv before you destroy this wxDataOutputStream instance! It is - recommended to use default value (UTF-8). + Charset conversion object object used to encoding Unicode + strings before writing them to the stream + in Unicode mode (see WriteString() + documentation for detailed description). Note that you must not destroy + conv before you destroy this wxDataOutputStream instance! It is + recommended to use default value (UTF-8). */ wxDataOutputStream(wxOutputStream& stream); wxDataOutputStream(wxOutputStream& stream); @@ -57,7 +55,7 @@ public: ~wxDataOutputStream(); /** - If @e be_order is @true, all data will be written in big-endian + If @a be_order is @true, all data will be written in big-endian order, e.g. for reading on a Sparc or from Java-Streams (which always use big-endian order), otherwise data will be written in little-endian order. @@ -67,52 +65,51 @@ public: //@{ /** Writes an array of 16 bit unsigned integer to the stream. The amount of - 16 bit unsigned integer to write is specified with the @e size variable. + 16 bit unsigned integer to write is specified with the @a size variable. */ void Write16(wxUint16 i16); - void Write16(const wxUint16 * buffer, size_t size); + void Write16(const wxUint16* buffer, size_t size); //@} //@{ /** Writes an array of 32 bit unsigned integer to the stream. The amount of - 32 bit unsigned integer to write is specified with the @e size variable. + 32 bit unsigned integer to write is specified with the @a size variable. */ void Write32(wxUint32 i32); - void Write32(const wxUint32 * buffer, size_t size); + void Write32(const wxUint32* buffer, size_t size); //@} //@{ /** Writes an array of 64 bit unsigned integer to the stream. The amount of - 64 bit unsigned integer to write is specified with the @e size variable. + 64 bit unsigned integer to write is specified with the @a size variable. */ void Write64(wxUint64 i64); - void Write64(const wxUint64 * buffer, size_t size); + void Write64(const wxUint64* buffer, size_t size); //@} //@{ /** Writes an array of bytes to the stream. The amount of bytes to write is - specified with the @e size variable. + specified with the @a size variable. */ void Write8(wxUint8 i8); - void Write8(const wxUint8 * buffer, size_t size); + void Write8(const wxUint8* buffer, size_t size); //@} //@{ /** Writes an array of double to the stream. The amount of double to write is - specified with the @e size variable. + specified with the @a size variable. */ void WriteDouble(double f); - void WriteDouble(const double * buffer, size_t size); + void WriteDouble(const double* buffer, size_t size); //@} /** - Writes @e string to the stream. Actually, this method writes the size of - the string before writing @e string itself. - + Writes @a string to the stream. Actually, this method writes the size of + the string before writing @a string itself. In ANSI build of wxWidgets, the string is written to the stream in exactly same way it is represented in memory. In Unicode build, however, the string is first converted to multibyte representation with @e conv object passed @@ -169,18 +166,16 @@ public: //@{ /** ) - Constructs a datastream object from an input stream. Only read methods will be available. The second form is only available in Unicode build of wxWidgets. @param stream - The input stream. - + The input stream. @param conv - Charset conversion object object used to decode strings in Unicode - mode (see ReadString() - documentation for detailed description). Note that you must not destroy - conv before you destroy this wxDataInputStream instance! + Charset conversion object object used to decode strings in Unicode + mode (see ReadString() + documentation for detailed description). Note that you must not destroy + conv before you destroy this wxDataInputStream instance! */ wxDataInputStream(wxInputStream& stream); wxDataInputStream(wxInputStream& stream); @@ -192,7 +187,7 @@ public: ~wxDataInputStream(); /** - If @e be_order is @true, all data will be read in big-endian + If @a be_order is @true, all data will be read in big-endian order, such as written by programs on a big endian architecture (e.g. Sparc) or written by Java-Streams (which always use big-endian order). @@ -202,61 +197,59 @@ public: //@{ /** Reads 16 bit unsigned integers from the stream in a specified buffer. the - amount of 16 bit unsigned integer to read is specified by the @e size variable. + amount of 16 bit unsigned integer to read is specified by the @a size variable. */ wxUint16 Read16(); - void Read16(wxUint16 * buffer, size_t size); + void Read16(wxUint16* buffer, size_t size); //@} //@{ /** Reads 32 bit unsigned integers from the stream in a specified buffer. the amount of - 32 bit unsigned integer to read is specified by the @e size variable. + 32 bit unsigned integer to read is specified by the @a size variable. */ wxUint32 Read32(); - void Read32(wxUint32 * buffer, size_t size); + void Read32(wxUint32* buffer, size_t size); //@} //@{ /** Reads 64 bit unsigned integers from the stream in a specified buffer. the amount of - 64 bit unsigned integer to read is specified by the @e size variable. + 64 bit unsigned integer to read is specified by the @a size variable. */ wxUint64 Read64(); - void Read64(wxUint64 * buffer, size_t size); + void Read64(wxUint64* buffer, size_t size); //@} //@{ /** Reads bytes from the stream in a specified buffer. The amount of - bytes to read is specified by the @e size variable. + bytes to read is specified by the @a size variable. */ wxUint8 Read8(); - void Read8(wxUint8 * buffer, size_t size); + void Read8(wxUint8* buffer, size_t size); //@} //@{ /** Reads double data (IEEE encoded) from the stream in a specified buffer. the amount of - double to read is specified by the @e size variable. + double to read is specified by the @a size variable. */ double ReadDouble(); - void ReadDouble(double * buffer, size_t size); + void ReadDouble(double* buffer, size_t size); //@} /** Reads a string from a stream. Actually, this function first reads a long integer specifying the length of the string (without the last null character) and then reads the string. - In Unicode build of wxWidgets, the fuction first reads multibyte (char*) string from the stream and then converts it to Unicode using the @e conv object passed to constructor and returns the result as wxString. You are responsible for using the same convertor as when writing the stream. - See also wxDataOutputStream::WriteString. */ wxString ReadString(); diff --git a/interface/dc.h b/interface/dc.h index d25db62d96..1d079fb67d 100644 --- a/interface/dc.h +++ b/interface/dc.h @@ -42,78 +42,72 @@ public: logical function, whether to use a bitmap mask, and mask source position. @param xdest - Destination device context x position. - + Destination device context x position. @param ydest - Destination device context y position. - + Destination device context y position. @param width - Width of source area to be copied. - + Width of source area to be copied. @param height - Height of source area to be copied. - + Height of source area to be copied. @param source - Source device context. - + Source device context. @param xsrc - Source device context x position. - + Source device context x position. @param ysrc - Source device context y position. - + Source device context y position. @param logicalFunc - Logical function to use: see SetLogicalFunction(). - + Logical function to use: see SetLogicalFunction(). @param useMask - If @true, Blit does a transparent blit using the mask that is associated with - the bitmap - selected into the source device context. The Windows implementation does the - following if MaskBlt cannot be used: - - Creates a temporary bitmap and copies the destination area into it. - Copies the source area into the temporary bitmap using the specified logical - function. - Sets the masked area in the temporary bitmap to BLACK by ANDing the - mask bitmap with the temp bitmap with the foreground colour set to WHITE - and the bg colour set to BLACK. - Sets the unmasked area in the destination area to BLACK by ANDing the - mask bitmap with the destination area with the foreground colour set to BLACK - and the background colour set to WHITE. - ORs the temporary bitmap with the destination area. - Deletes the temporary bitmap. - - This sequence of operations ensures that the source's transparent area need not - be black, - and logical functions are supported. - - Note: on Windows, blitting with masks can be speeded up considerably by + If @true, Blit does a transparent blit using the mask that is associated + with the bitmap + selected into the source device context. The Windows implementation does + the following if MaskBlt cannot be used: + + + Creates a temporary bitmap and copies the destination area into it. + Copies the source area into the temporary bitmap using the specified + logical function. + Sets the masked area in the temporary bitmap to BLACK by ANDing the + mask bitmap with the temp bitmap with the foreground colour set to WHITE + and the bg colour set to BLACK. + Sets the unmasked area in the destination area to BLACK by ANDing the + mask bitmap with the destination area with the foreground colour set to + BLACK + and the background colour set to WHITE. + ORs the temporary bitmap with the destination area. + Deletes the temporary bitmap. + + + This sequence of operations ensures that the source's transparent area need + not be black, + and logical functions are supported. + Note: on Windows, blitting with masks can be speeded up considerably by compiling - wxWidgets with the wxUSE_DC_CACHE option enabled. You can also influence + wxWidgets with the wxUSE_DC_CACHE option enabled. You can also influence whether MaskBlt - or the explicit mask blitting code above is used, by using wxSystemOptions and - setting the no-maskblt option to 1. + or the explicit mask blitting code above is used, by using wxSystemOptions + and + setting the no-maskblt option to 1. @param xsrcMask - Source x position on the mask. If both xsrcMask and ysrcMask are -1, xsrc and - ysrc - will be assumed for the mask source position. Currently only implemented on + Source x position on the mask. If both xsrcMask and ysrcMask are -1, xsrc + and ysrc + will be assumed for the mask source position. Currently only implemented on Windows. - @param ysrcMask - Source y position on the mask. If both xsrcMask and ysrcMask are -1, xsrc and - ysrc - will be assumed for the mask source position. Currently only implemented on + Source y position on the mask. If both xsrcMask and ysrcMask are -1, xsrc + and ysrc + will be assumed for the mask source position. Currently only implemented on Windows. @remarks There is partial support for Blit in wxPostScriptDC, under X. - @sa StretchBlit(), wxMemoryDC, wxBitmap, wxMask + @see StretchBlit(), wxMemoryDC, wxBitmap, wxMask */ bool Blit(wxCoord xdest, wxCoord ydest, wxCoord width, wxCoord height, wxDC* source, wxCoord xsrc, wxCoord ysrc, int logicalFunc = wxCOPY, - bool useMask = @false, + bool useMask = false, wxCoord xsrcMask = -1, wxCoord ysrcMask = -1); @@ -122,7 +116,7 @@ public: MinX(), MaxX() and MinY(), MaxY() functions. - @sa ResetBoundingBox() + @see ResetBoundingBox() */ void CalcBoundingBox(wxCoord x, wxCoord y); @@ -182,7 +176,6 @@ public: y1) and ending at (@e x2, y2). The current pen is used for the outline and the current brush for filling the shape. - The arc is drawn in an anticlockwise direction from the start point to the end point. */ @@ -190,10 +183,9 @@ public: wxCoord xc, wxCoord yc); /** - Draw a bitmap on the device context at the specified point. If @e transparent + Draw a bitmap on the device context at the specified point. If @a transparent is @true and the bitmap has a transparency mask, the bitmap will be drawn transparently. - When drawing a mono-bitmap, the current text foreground colour will be used to draw the foreground of the bitmap (all bits set to 1), and the current text background colour to @@ -210,14 +202,14 @@ public: */ void DrawCheckMark(wxCoord x, wxCoord y, wxCoord width, wxCoord height); - void DrawCheckMark(const wxRect & rect); + void DrawCheckMark(const wxRect& rect); //@} //@{ /** Draws a circle with the given centre and radius. - @sa DrawEllipse() + @see DrawEllipse() */ void DrawCircle(wxCoord x, wxCoord y, wxCoord radius); void DrawCircle(const wxPoint& pt, wxCoord radius); @@ -229,7 +221,7 @@ public: left corner and the given size or directly. The current pen is used for the outline and the current brush for filling the shape. - @sa DrawCircle() + @see DrawCircle() */ void DrawEllipse(wxCoord x, wxCoord y, wxCoord width, wxCoord height); @@ -240,20 +232,17 @@ public: /** Draws an arc of an ellipse. The current pen is used for drawing the arc and the current brush is used for drawing the pie. - - @e x and @e y specify the x and y coordinates of the upper-left corner of the + @a x and @a y specify the x and y coordinates of the upper-left corner of the rectangle that contains the ellipse. - - @e width and @e height specify the width and height of the rectangle that + @a width and @a height specify the width and height of the rectangle that contains the ellipse. - - @e start and @e end specify the start and end of the arc relative to the + @a start and @a end specify the start and end of the arc relative to the three-o'clock position from the center of the rectangle. Angles are specified in degrees (360 is a complete circle). Positive values mean - counter-clockwise motion. If @e start is equal to @e end, a + counter-clockwise motion. If @a start is equal to @e end, a complete ellipse will be drawn. */ void DrawEllipticArc(wxCoord x, wxCoord y, wxCoord width, @@ -280,7 +269,7 @@ public: const wxRect& rect, int alignment = wxALIGN_LEFT | wxALIGN_TOP, int indexAccel = -1, - wxRect * rectBounding = @NULL); + wxRect* rectBounding = NULL); void DrawLabel(const wxString& text, const wxRect& rect, int alignment = wxALIGN_LEFT | wxALIGN_TOP, int indexAccel = -1); @@ -302,7 +291,7 @@ public: */ void DrawLines(int n, wxPoint points[], wxCoord xoffset = 0, wxCoord yoffset = 0); - void DrawLines(const wxPointList * points, + void DrawLines(const wxPointList* points, wxCoord xoffset = 0, wxCoord yoffset = 0); //@} @@ -316,21 +305,16 @@ public: /** Draws two or more filled polygons using an array of @e points, adding the optional offset coordinates. - Notice that for the platforms providing a native implementation of this function (Windows and PostScript-based wxDC currently), this is more efficient than using DrawPolygon() in a loop. - - @e n specifies the number of polygons to draw, the array @e count of size - @e n specifies the number of points in each of the polygons in the + @a n specifies the number of polygons to draw, the array @e count of size + @a n specifies the number of points in each of the polygons in the @e points array. - The last argument specifies the fill rule: @b wxODDEVEN_RULE (the default) or @b wxWINDING_RULE. - The current pen is used for drawing the outline, and the current brush for filling the shape. Using a transparent brush suppresses filling. - The polygons maybe disjoint or overlapping. Each polygon specified in a call to @b DrawPolyPolygon must be closed. Unlike polygons created by the DrawPolygon() member function, the polygons created by @@ -345,20 +329,17 @@ public: /** This method draws a filled polygon using a list of wxPoints, adding the optional offset coordinate. - The last argument specifies the fill rule: @b wxODDEVEN_RULE (the default) or @b wxWINDING_RULE. - The current pen is used for drawing the outline, and the current brush for filling the shape. Using a transparent brush suppresses filling. The programmer is responsible for deleting the list of points. - Note that wxWidgets automatically closes the first and last points. */ void DrawPolygon(int n, wxPoint points[], wxCoord xoffset = 0, wxCoord yoffset = 0, int fill_style = wxODDEVEN_RULE); - void DrawPolygon(const wxPointList * points, + void DrawPolygon(const wxPointList* points, wxCoord xoffset = 0, wxCoord yoffset = 0, int fill_style = wxODDEVEN_RULE); @@ -373,14 +354,13 @@ public: wxCoord height); /** - Draws the text rotated by @e angle degrees. - + Draws the text rotated by @a angle degrees. @b NB: 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. - @sa DrawText() + @see DrawText() */ void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y, double angle); @@ -390,9 +370,8 @@ public: size. The corners are quarter-circles using the given radius. The current pen is used for the outline and the current brush for filling the shape. - - If @e radius is positive, the value is assumed to be the - radius of the rounded corner. If @e radius is negative, + If @a radius is positive, the value is assumed to be the + radius of the rounded corner. If @a radius is negative, the absolute value is assumed to be the @e proportion of the smallest dimension of the rectangle. This means that the corner can be a sensible size relative to the size of the rectangle, and also avoids @@ -408,7 +387,7 @@ public: Draws a three-point spline using the current pen. */ void DrawSpline(int n, wxPoint points[]); - void DrawSpline(const wxPointList * points); + void DrawSpline(const wxPointList* points); void DrawSpline(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, wxCoord x3, @@ -418,12 +397,10 @@ public: /** Draws a text string at the specified point, using the current text font, and the current text foreground and background colours. - The coordinates refer to the top-left corner of the rectangle bounding 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 @ref getlogicalfunction() "logical function" is used by this function but it is ignored by wxMSW. Thus, you should avoid using logical functions @@ -444,19 +421,16 @@ public: /** Flood fills the device context starting from the given point, using the @e current brush colour, and using a style: - wxFLOOD_SURFACE: the flooding occurs until a colour other than the given colour is encountered. wxFLOOD_BORDER: the area to be flooded is bounded by the given colour. - Returns @false if the operation failed. - @e Note: The present implementation for non-Windows platforms may fail to find colour borders if the pixels do not match the colour exactly. However the function will still return @true. */ bool FloodFill(wxCoord x, wxCoord y, const wxColour& colour, - int style=wxFLOOD_SURFACE); + int style = wxFLOOD_SURFACE); /** Gets the brush used for painting the background (see wxDC::SetBackground). @@ -466,7 +440,7 @@ public: /** Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT. - @sa SetBackgroundMode() + @see SetBackgroundMode() */ int GetBackgroundMode(); @@ -494,7 +468,7 @@ public: /** Returns the depth (number of bits/pixel) of this DC. - @sa wxDisplayDepth + @see wxDisplayDepth */ int GetDepth(); @@ -513,7 +487,7 @@ public: @c wxLayout_RightToLeft. If RTL layout is not supported, the return value will be @c wxLayout_Default. - @sa SetLayoutDirection() + @see SetLayoutDirection() */ wxLayoutDirection GetLayoutDirection(); @@ -530,41 +504,38 @@ public: //@{ /** Gets the dimensions of the string using the currently selected font. - @e string is the text string to measure, @e heightLine, if non @NULL, + @a string is the text string to measure, @e heightLine, if non @NULL, is where to store the height of a single line. - - The text extent is returned in @e w and @e h pointers (first form) or as + The text extent is returned in @a w and @a h pointers (first form) or as a wxSize object (second form). - - If the optional parameter @e font is specified and valid, then it is used + If the optional parameter @a font is specified and valid, then it is used for the text extent calculation. Otherwise the currently selected font is. - Note that this function works both with single-line and multi-line strings. - @sa wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent() + @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent() */ - void GetMultiLineTextExtent(const wxString& string, wxCoord * w, - wxCoord * h, - wxCoord * heightLine = @NULL, - wxFont * font = @NULL); + void GetMultiLineTextExtent(const wxString& string, wxCoord* w, + wxCoord* h, + wxCoord* heightLine = NULL, + wxFont* font = NULL); wxSize GetMultiLineTextExtent(const wxString& string); //@} /** Returns the resolution of the device in pixels per inch. */ -#define wxSize GetPPI() /* implementation is private */ + wxSize GetPPI(); /** - Fills the @e widths array with the widths from the beginning of - @e text to the corresponding character of @e text. The generic + Fills the @a widths array with the widths from the beginning of + @a text to the corresponding character of @e text. The generic version simply builds a running total of the widths of each character using GetTextExtent(), however if the various platforms have a native API function that is faster or more accurate than the generic implementation then it should be used instead. - @sa GetMultiLineTextExtent(), GetTextExtent() + @see GetMultiLineTextExtent(), GetTextExtent() */ bool GetPartialTextExtents(const wxString& text, wxArrayInt& widths); @@ -575,12 +546,11 @@ public: const wxPen GetPen(); /** - Gets in @e colour the colour at the specified location. + Gets in @a colour the colour at the specified location. Not available for wxPostScriptDC or wxMetafileDC. - Note that setting a pixel can be done using DrawPoint(). */ - bool GetPixel(wxCoord x, wxCoord y, wxColour * colour); + bool GetPixel(wxCoord x, wxCoord y, wxColour* colour); //@{ /** @@ -592,19 +562,16 @@ public: printer page: - @b GetSize() - Returns a Wx::Size @b GetSizeWH() - Returns a 2-element list @c ( width, height ) */ - void GetSize(wxCoord * width, wxCoord * height); + void GetSize(wxCoord* width, wxCoord* height); wxSize GetSize(); //@} @@ -612,7 +579,7 @@ public: /** Returns the horizontal and vertical resolution in millimetres. */ - void GetSizeMM(wxCoord * width, wxCoord * height); + void GetSizeMM(wxCoord* width, wxCoord* height); wxSize GetSizeMM(); //@} @@ -624,27 +591,24 @@ public: //@{ /** Gets the dimensions of the string using the currently selected font. - @e string is the text string to measure, @e descent is the + @a string is the text string to measure, @a descent is the dimension from the baseline of the font to the bottom of the - descender, and @e externalLeading is any extra vertical space added + descender, and @a externalLeading is any extra vertical space added to the font by the font designer (usually is zero). - - The text extent is returned in @e w and @e h pointers (first form) or as + The text extent is returned in @a w and @a h pointers (first form) or as a wxSize object (second form). - - If the optional parameter @e font is specified and valid, then it is used + If the optional parameter @a font is specified and valid, then it is used for the text extent calculation. Otherwise the currently selected font is. - Note that this function only works with single-line strings. - @sa wxFont, SetFont(), GetPartialTextExtents(), - GetMultiLineTextExtent() - */ - void GetTextExtent(const wxString& string, wxCoord * w, - wxCoord * h, - wxCoord * descent = @NULL, - wxCoord * externalLeading = @NULL, - const wxFont * font = @NULL); + @see wxFont, SetFont(), GetPartialTextExtents(), + GetMultiLineTextExtent() + */ + void GetTextExtent(const wxString& string, wxCoord* w, + wxCoord* h, + wxCoord* descent = NULL, + wxCoord* externalLeading = NULL, + const wxFont* font = NULL); wxSize GetTextExtent(const wxString& string); //@} @@ -661,13 +625,11 @@ public: //@{ /** Fill the area specified by rect with a radial gradient, starting from - @e initialColour at the centre of the circle and fading to @e destColour + @a initialColour at the centre of the circle and fading to @a destColour on the circle outside. - - @e circleCenter are the relative coordinates of centre of the circle in + @a circleCenter are the relative coordinates of centre of the circle in the specified @e rect. If not specified, the cercle is placed at the centre of rect. - @b Note: Currently this function is very slow, don't use it for real-time drawing. */ @@ -681,11 +643,11 @@ public: //@} /** - Fill the area specified by @e rect with a linear gradient, starting from - @e initialColour and eventually fading to @e destColour. The - @e nDirection specifies the direction of the colour change, default is to - use @e initialColour on the left part of the rectangle and - @e destColour on the right one. + Fill the area specified by @a rect with a linear gradient, starting from + @a initialColour and eventually fading to @e destColour. The + @a nDirection specifies the direction of the colour change, default is to + use @a initialColour on the left part of the rectangle and + @a destColour on the right one. */ void GradientFillLinear(const wxRect& rect, const wxColour& initialColour, @@ -695,7 +657,7 @@ public: /** Returns @true if the DC is ok to use. */ -#define bool Ok() /* implementation is private */ + bool Ok(); /** Converts logical X coordinate to device coordinate, using the current @@ -726,28 +688,28 @@ public: /** Gets the maximum horizontal extent used in drawing commands so far. */ -#define wxCoord MaxX() /* implementation is private */ + wxCoord MaxX(); /** Gets the maximum vertical extent used in drawing commands so far. */ -#define wxCoord MaxY() /* implementation is private */ + wxCoord MaxY(); /** Gets the minimum horizontal extent used in drawing commands so far. */ -#define wxCoord MinX() /* implementation is private */ + wxCoord MinX(); /** Gets the minimum vertical extent used in drawing commands so far. */ -#define wxCoord MinY() /* implementation is private */ + wxCoord MinY(); /** Resets the bounding box: after a call to this function, the bounding box doesn't contain anything. - @sa CalcBoundingBox() + @see CalcBoundingBox() */ void ResetBoundingBox(); @@ -757,12 +719,11 @@ public: x axis from left to right and y axis from top down. @param xLeftRight - True to set the x axis orientation to the natural - left to right orientation, @false to invert it. - + True to set the x axis orientation to the natural + left to right orientation, @false to invert it. @param yBottomUp - True to set the y axis orientation to the natural - bottom up orientation, @false to invert it. + True to set the y axis orientation to the natural + bottom up orientation, @false to invert it. */ void SetAxisOrientation(bool xLeftRight, bool yBottomUp); @@ -772,20 +733,17 @@ public: void SetBackground(const wxBrush& brush); /** - @e mode may be one of wxSOLID and wxTRANSPARENT. This setting determines + @a mode may be one of wxSOLID and wxTRANSPARENT. This setting determines whether text will be drawn with a background colour or not. */ void SetBackgroundMode(int mode); /** Sets the current brush for the DC. - If the argument is wxNullBrush, the current brush is selected out of the device context (leaving wxDC without any valid brush), allowing the current brush to be destroyed safely. - See also wxBrush. - See also wxMemoryDC for the interpretation of colours when drawing into a monochrome bitmap. */ @@ -798,12 +756,11 @@ public: clipping region. You should call DestroyClippingRegion() if you want to set the clipping region exactly to the region specified. - The clipping region is an area to which drawing is restricted. Possible uses for the clipping region are for clipping text or for speeding up window redraws when only a known area of the screen is damaged. - @sa DestroyClippingRegion(), wxRegion + @see DestroyClippingRegion(), wxRegion */ void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width, wxCoord height); @@ -815,7 +772,6 @@ public: /** Sets the device origin (i.e., the origin in pixels after scaling has been applied). - This function may be useful in Windows printing operations for placing a graphic on a page. */ @@ -824,16 +780,15 @@ public: /** Sets the current font for the DC. It must be a valid font, in particular you should not pass @c wxNullFont to this method. - See also wxFont. */ void SetFont(const wxFont& font); /** - Sets the current layout direction for the device context. @e dir may be either + Sets the current layout direction for the device context. @a dir may be either @c wxLayout_Default, @c wxLayout_LeftToRight or @c wxLayout_RightToLeft. - @sa GetLayoutDirection() + @see GetLayoutDirection() */ void SetLayoutDirection(wxLayoutDirection dir); @@ -842,10 +797,10 @@ public: a source pixel (from a pen or brush colour, or source device context if using wxDC::Blit) combines with a destination pixel in the current device context. - The possible values and their meaning in terms of source and destination pixel values are as follows: + The default is wxCOPY, which simply draws with the current colour. The others combine the current colour and the background using a logical operation. wxINVERT is commonly used for drawing rubber bands or @@ -861,38 +816,30 @@ public: wxDC::SetUserScale) scales the text appropriately. In Windows, scalable TrueType fonts are always used; in X, results depend on availability of fonts, but usually a reasonable match is found. - The coordinate origin is always at the top left of the screen/printer. - Drawing to a Windows printer device context uses the current mapping mode, but mapping mode is currently ignored for PostScript output. - The mapping mode can be one of the following: wxMM_TWIPS - Each logical unit is 1/20 of a point, or 1/1440 of an inch. wxMM_POINTS - Each logical unit is a point, or 1/72 of an inch. wxMM_METRIC - Each logical unit is 1 mm. wxMM_LOMETRIC - Each logical unit is 1/10 of a mm. wxMM_TEXT - Each logical unit is 1 device pixel. */ void SetMapMode(int int); @@ -902,18 +849,15 @@ public: or bitmap associated with the DC. If the argument is wxNullPalette, the current palette is selected out of the device context, and the original palette restored. - See wxPalette for further details. */ void SetPalette(const wxPalette& palette); /** Sets the current pen for the DC. - If the argument is wxNullPen, the current pen is selected out of the device context (leaving wxDC without any valid pen), allowing the current brush to be destroyed safely. - See also wxMemoryDC for the interpretation of colours when drawing into a monochrome bitmap. */ @@ -926,7 +870,6 @@ public: /** Sets the current text foreground colour for the DC. - See also wxMemoryDC for the interpretation of colours when drawing into a monochrome bitmap. */ @@ -956,73 +899,65 @@ public: and mask source position. @param xdest - Destination device context x position. - + Destination device context x position. @param ydest - Destination device context y position. - + Destination device context y position. @param dstWidth - Width of destination area. - + Width of destination area. @param dstHeight - Height of destination area. - + Height of destination area. @param source - Source device context. - + Source device context. @param xsrc - Source device context x position. - + Source device context x position. @param ysrc - Source device context y position. - + Source device context y position. @param srcWidth - Width of source area to be copied. - + Width of source area to be copied. @param srcHeight - Height of source area to be copied. - + Height of source area to be copied. @param logicalFunc - Logical function to use: see SetLogicalFunction(). - + Logical function to use: see SetLogicalFunction(). @param useMask - If @true, Blit does a transparent blit using the mask that is associated with - the bitmap - selected into the source device context. The Windows implementation does the - following if MaskBlt cannot be used: - - Creates a temporary bitmap and copies the destination area into it. - Copies the source area into the temporary bitmap using the specified logical - function. - Sets the masked area in the temporary bitmap to BLACK by ANDing the - mask bitmap with the temp bitmap with the foreground colour set to WHITE - and the background colour set to BLACK. - Sets the unmasked area in the destination area to BLACK by ANDing the - mask bitmap with the destination area with the foreground colour set to BLACK - and the background colour set to WHITE. - ORs the temporary bitmap with the destination area. - Deletes the temporary bitmap. - - This sequence of operations ensures that the source's transparent area need not - be black, - and logical functions are supported. - - Note: on Windows, blitting with masks can be speeded up considerably by + If @true, Blit does a transparent blit using the mask that is associated + with the bitmap + selected into the source device context. The Windows implementation does + the following if MaskBlt cannot be used: + + + Creates a temporary bitmap and copies the destination area into it. + Copies the source area into the temporary bitmap using the specified + logical function. + Sets the masked area in the temporary bitmap to BLACK by ANDing the + mask bitmap with the temp bitmap with the foreground colour set to WHITE + and the background colour set to BLACK. + Sets the unmasked area in the destination area to BLACK by ANDing the + mask bitmap with the destination area with the foreground colour set to + BLACK + and the background colour set to WHITE. + ORs the temporary bitmap with the destination area. + Deletes the temporary bitmap. + + + This sequence of operations ensures that the source's transparent area need + not be black, + and logical functions are supported. + Note: on Windows, blitting with masks can be speeded up considerably by compiling - wxWidgets with the wxUSE_DC_CACHE option enabled. You can also influence + wxWidgets with the wxUSE_DC_CACHE option enabled. You can also influence whether MaskBlt - or the explicit mask blitting code above is used, by using wxSystemOptions and - setting the no-maskblt option to 1. + or the explicit mask blitting code above is used, by using wxSystemOptions + and + setting the no-maskblt option to 1. @param xsrcMask - Source x position on the mask. If both xsrcMask and ysrcMask are -1, xsrc and - ysrc - will be assumed for the mask source position. Currently only implemented on + Source x position on the mask. If both xsrcMask and ysrcMask are -1, xsrc + and ysrc + will be assumed for the mask source position. Currently only implemented on Windows. - @param ysrcMask - Source y position on the mask. If both xsrcMask and ysrcMask are -1, xsrc and - ysrc - will be assumed for the mask source position. Currently only implemented on + Source y position on the mask. If both xsrcMask and ysrcMask are -1, xsrc + and ysrc + will be assumed for the mask source position. Currently only implemented on Windows. @remarks There is partial support for Blit in wxPostScriptDC, under X. @@ -1034,7 +969,7 @@ public: wxCoord srcWidth, wxCoord srcHeight, int logicalFunc = wxCOPY, - bool useMask = @false, + bool useMask = false, wxCoord xsrcMask = -1, wxCoord ysrcMask = -1); }; @@ -1075,10 +1010,9 @@ class wxDCClipper public: //@{ /** - Sets the clipping region to the specified region @e r or rectangle specified - by either a single @e rect parameter or its position (@e x and @e y) - and size (@e w ad @e h). - + Sets the clipping region to the specified region @a r or rectangle specified + by either a single @a rect parameter or its position (@a x and @e y) + and size (@a w ad @e h). The clipping region is automatically unset when this object is destroyed. */ wxDCClipper(wxDC& dc, const wxRegion& r); diff --git a/interface/dcbuffer.h b/interface/dcbuffer.h index 863ddf232b..912e377389 100644 --- a/interface/dcbuffer.h +++ b/interface/dcbuffer.h @@ -48,37 +48,35 @@ public: /** If you use the first, default, constructor, you must call one of the Init() methods later in order to use the object. - The other constructors initialize the object immediately and @c Init() must not be called after using them. @param dc - The underlying DC: everything drawn to this object will be - flushed to this DC when this object is destroyed. You may pass @NULL - in order to just initialize the buffer, and not flush it. - + The underlying DC: everything drawn to this object will be + flushed to this DC when this object is destroyed. You may pass @NULL + in order to just initialize the buffer, and not flush it. @param area - The size of the bitmap to be used for buffering (this bitmap is - created internally when it is not given explicitly). - + The size of the bitmap to be used for buffering (this bitmap is + created internally when it is not given explicitly). @param buffer - Explicitly provided bitmap to be used for buffering: this is - the most efficient solution as the bitmap doesn't have to be recreated each - time but it also requires more memory as the bitmap is never freed. The bitmap - should have appropriate size, anything drawn outside of its bounds is clipped. - - @param style - wxBUFFER_CLIENT_AREA to indicate that just the client area of - the window is buffered, or wxBUFFER_VIRTUAL_AREA to indicate that the buffer + Explicitly provided bitmap to be used for buffering: this is + the most efficient solution as the bitmap doesn't have to be recreated each + time but it also requires more memory as the bitmap is never freed. The bitmap - covers the virtual area (in which case PrepareDC is automatically called for - the actual window - device context). + should have appropriate size, anything drawn outside of its bounds is + clipped. + @param style + wxBUFFER_CLIENT_AREA to indicate that just the client area of + the window is buffered, or wxBUFFER_VIRTUAL_AREA to indicate that the + buffer bitmap + covers the virtual area (in which case PrepareDC is automatically called + for the actual window + device context). */ wxBufferedDC(); - wxBufferedDC(wxDC * dc, const wxSize& area, + wxBufferedDC(wxDC* dc, const wxSize& area, int style = wxBUFFER_CLIENT_AREA); - wxBufferedDC(wxDC * dc, wxBitmap& buffer, + wxBufferedDC(wxDC* dc, wxBitmap& buffer, int style = wxBUFFER_CLIENT_AREA); //@} @@ -93,9 +91,9 @@ public: These functions initialize the object created using the default constructor. Please see @ref ctor() "constructors documentation" for details. */ - void Init(wxDC * dc, const wxSize& area, + void Init(wxDC* dc, const wxSize& area, int style = wxBUFFER_CLIENT_AREA); - void Init(wxDC * dc, wxBitmap& buffer, + void Init(wxDC* dc, wxBitmap& buffer, int style = wxBUFFER_CLIENT_AREA); //@} }; @@ -131,7 +129,7 @@ public: /** Constructor. Pass a pointer to the window on which you wish to paint. */ - wxAutoBufferedPaintDC(wxWindow * window); + wxAutoBufferedPaintDC(wxWindow* window); }; @@ -165,8 +163,7 @@ public: As with @ref wxBufferedDC::ctor wxBufferedDC, you may either provide the bitmap to be used for buffering or let this object create one internally (in the latter case, the size of the client part of the window is used). - - Pass wxBUFFER_CLIENT_AREA for the @e style parameter to indicate that just the + Pass wxBUFFER_CLIENT_AREA for the @a style parameter to indicate that just the client area of the window is buffered, or wxBUFFER_VIRTUAL_AREA to indicate that the buffer bitmap @@ -174,9 +171,9 @@ public: the actual window device context). */ - wxBufferedPaintDC(wxWindow * window, wxBitmap& buffer, + wxBufferedPaintDC(wxWindow* window, wxBitmap& buffer, int style = wxBUFFER_CLIENT_AREA); - wxBufferedPaintDC(wxWindow * window, + wxBufferedPaintDC(wxWindow* window, int style = wxBUFFER_CLIENT_AREA); //@} diff --git a/interface/dcmemory.h b/interface/dcmemory.h index de07c92384..af09579f06 100644 --- a/interface/dcmemory.h +++ b/interface/dcmemory.h @@ -41,17 +41,15 @@ public: this is the function you should use when you select a bitmap because you want to modify it, e.g. drawing on this DC. - Using SelectObjectAsSource() when modifying the bitmap may incurr some problems related to wxBitmap being a reference counted object (see @ref overview_trefcount "reference counting overview"). - Also, before using the updated bitmap data, make sure to select it out of context first (for example by selecting wxNullBitmap into the device context). - @sa wxDC::DrawBitmap + @see wxDC::DrawBitmap */ void SelectObject(wxBitmap& bitmap); @@ -61,7 +59,6 @@ public: the DC (and therefore the bitmap) and also to use wxDC::Blit to copy the bitmap to a window. For this purpose, you may find wxDC::DrawIcon easier to use instead. - If the argument is wxNullBitmap (or some other uninitialised wxBitmap) the current bitmap is selected out of the device context, and the original bitmap restored, allowing diff --git a/interface/dcmirror.h b/interface/dcmirror.h index 7df4987c1b..c0ce2d50ed 100644 --- a/interface/dcmirror.h +++ b/interface/dcmirror.h @@ -27,8 +27,7 @@ public: /** Creates a (maybe) mirrored DC associated with the real @e dc. Everything drawn on wxMirrorDC will appear (and maybe mirrored) on @e dc. - - @e mirror specifies if we do mirror (if it is @true) or not (if it is + @a mirror specifies if we do mirror (if it is @true) or not (if it is @false). */ wxMirrorDC(wxDC& dc, bool mirror); diff --git a/interface/dcprint.h b/interface/dcprint.h index 10a882a5e8..12ccf3dda1 100644 --- a/interface/dcprint.h +++ b/interface/dcprint.h @@ -28,17 +28,16 @@ public: /** Constructor. With empty strings for the first three arguments, the default printer dialog is - displayed. @e device indicates the type of printer and @e output - is an optional file for printing to. The @e driver parameter is + displayed. @a device indicates the type of printer and @e output + is an optional file for printing to. The @a driver parameter is currently unused. Use the @e Ok member to test whether the constructor was successful in creating a usable device context. - This constructor is deprecated and retained only for backward compatibility. */ wxPrinterDC(const wxPrintData& printData); wxPrinterDC(const wxString& driver, const wxString& device, const wxString& output, - const bool interactive = @true, + const bool interactive = true, int orientation = wxPORTRAIT); //@} diff --git a/interface/dcps.h b/interface/dcps.h index 0d83ba5b45..547e68ccd6 100644 --- a/interface/dcps.h +++ b/interface/dcps.h @@ -22,23 +22,20 @@ class wxPostScriptDC : public wxDC public: //@{ /** - Constructor. @e output is an optional file for printing to, and if - @e interactive is @true a dialog box will be displayed for adjusting - various parameters. @e parent is the parent of the printer dialog box. - + Constructor. @a output is an optional file for printing to, and if + @a interactive is @true a dialog box will be displayed for adjusting + various parameters. @a parent is the parent of the printer dialog box. Use the @e Ok member to test whether the constructor was successful in creating a usable device context. - See @ref overview_printersettings "Printer settings" for functions to set and get PostScript printing settings. - This constructor and the global printer settings are now deprecated; use the wxPrintData constructor instead. */ wxPostScriptDC(const wxPrintData& printData); wxPostScriptDC(const wxString& output, - bool interactive = @true, - wxWindow * parent); + bool interactive = true, + wxWindow* parent); //@} /** @@ -84,7 +81,7 @@ void wxSetPrinterOptions(const wxString& options); Gets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0. */ -void wxGetPrinterTranslation(float * x, float * y); +void wxGetPrinterTranslation(float* x, float* y); /** Sets the scaling factor for PostScript output. The default is 1.0, 1.0. @@ -135,7 +132,7 @@ int wxGetPrinterMode(); /** Gets the scaling factor for PostScript output. The default is 1.0, 1.0. */ -void wxGetPrinterScaling(float * x, float * y); +void wxGetPrinterScaling(float* x, float* y); /** Sets the command used to view a PostScript file. The default depends on the diff --git a/interface/dcscreen.h b/interface/dcscreen.h index e85c7d16fd..7c4854c7ea 100644 --- a/interface/dcscreen.h +++ b/interface/dcscreen.h @@ -30,7 +30,6 @@ public: /** Use this in conjunction with StartDrawingOnTop(). - This function destroys the temporary window created to implement on-top drawing (X only). */ @@ -43,30 +42,26 @@ public: this, some window systems (such as X) only allow drawing to take place underneath other windows. - By using the first form of this function, an application is specifying that the area that will be drawn on coincides with the given window. - By using the second form, an application can specify an area of the screen which is to be drawn on. If @NULL is passed, the whole screen is available. - It is recommended that an area of the screen is specified because with large regions, flickering effects are noticeable when destroying the temporary transparent window used to implement this feature. - You might use this pair of functions when implementing a drag feature, for example as in the wxSplitterWindow implementation. @remarks This function is probably obsolete since the X implementations - allow drawing directly on the screen now. However, - the fact that this function allows the screen to be - refreshed afterwards, may be useful to some - applications. + allow drawing directly on the screen now. However, the + fact that this function allows the screen to be + refreshed afterwards, may be useful to some + applications. */ bool StartDrawingOnTop(wxWindow* window); - bool StartDrawingOnTop(wxRect* rect = @NULL); + bool StartDrawingOnTop(wxRect* rect = NULL); //@} }; diff --git a/interface/dcsvg.h b/interface/dcsvg.h index 34ff02def0..69a506710b 100644 --- a/interface/dcsvg.h +++ b/interface/dcsvg.h @@ -45,10 +45,10 @@ public: //@{ /** Constructors: - a filename @e f with default size 340x240 at 72.0 dots per inch (a frequent + a filename @a f with default size 340x240 at 72.0 dots per inch (a frequent screen resolution). - a filename @e f with size @e Width by @e Height at 72.0 dots per inch - a filename @e f with size @e Width by @e Height at @e dpi resolution. + a filename @a f with size @a Width by @a Height at 72.0 dots per inch + a filename @a f with size @a Width by @a Height at @a dpi resolution. */ wxSVGFileDC(wxString f); wxSVGFileDC(wxString f, int Width, int Height); @@ -131,7 +131,6 @@ public: y1) and ending at (@e x2, y2). The current pen is used for the outline and the current brush for filling the shape. - The arc is drawn in an anticlockwise direction from the start point to the end point. */ @@ -139,10 +138,9 @@ public: wxCoord xc, wxCoord yc); /** - Draw a bitmap on the device context at the specified point. If @e transparent + Draw a bitmap on the device context at the specified point. If @a transparent is @true and the bitmap has a transparency mask, the bitmap will be drawn transparently. - When drawing a mono-bitmap, the current text foreground colour will be used to draw the foreground of the bitmap (all bits set to 1), and the current text background colour to @@ -159,14 +157,14 @@ public: */ void DrawCheckMark(wxCoord x, wxCoord y, wxCoord width, wxCoord height); - void DrawCheckMark(const wxRect & rect); + void DrawCheckMark(const wxRect& rect); //@} //@{ /** Draws a circle with the given centre and radius. - @sa wxDC::DrawEllipse + @see wxDC::DrawEllipse */ void DrawCircle(wxCoord x, wxCoord y, wxCoord radius); void DrawCircle(const wxPoint& pt, wxCoord radius); @@ -178,7 +176,7 @@ public: left corner and the given size or directly. The current pen is used for the outline and the current brush for filling the shape. - @sa wxDC::DrawCircle + @see wxDC::DrawCircle */ void DrawEllipse(wxCoord x, wxCoord y, wxCoord width, wxCoord height); @@ -189,20 +187,17 @@ public: /** Draws an arc of an ellipse. The current pen is used for drawing the arc and the current brush is used for drawing the pie. - - @e x and @e y specify the x and y coordinates of the upper-left corner of the + @a x and @a y specify the x and y coordinates of the upper-left corner of the rectangle that contains the ellipse. - - @e width and @e height specify the width and height of the rectangle that + @a width and @a height specify the width and height of the rectangle that contains the ellipse. - - @e start and @e end specify the start and end of the arc relative to the + @a start and @a end specify the start and end of the arc relative to the three-o'clock position from the center of the rectangle. Angles are specified in degrees (360 is a complete circle). Positive values mean - counter-clockwise motion. If @e start is equal to @e end, a + counter-clockwise motion. If @a start is equal to @e end, a complete ellipse will be drawn. */ void DrawEllipticArc(wxCoord x, wxCoord y, wxCoord width, @@ -224,14 +219,14 @@ public: //@{ /** - Draws lines using an array of @e points of size @e n, or list of + Draws lines using an array of @a points of size @e n, or list of pointers to points, adding the optional offset coordinate. The current pen is used for drawing the lines. The programmer is responsible for deleting the list of points. */ void DrawLines(int n, wxPoint points[], wxCoord xoffset = 0, wxCoord yoffset = 0); - void DrawLines(wxList * points, wxCoord xoffset = 0, + void DrawLines(wxList* points, wxCoord xoffset = 0, wxCoord yoffset = 0); //@} @@ -242,22 +237,19 @@ public: //@{ /** - Draws a filled polygon using an array of @e points of size @e n, + Draws a filled polygon using an array of @a points of size @e n, or list of pointers to points, adding the optional offset coordinate. - The last argument specifies the fill rule: @b wxODDEVEN_RULE (the default) or @b wxWINDING_RULE. - The current pen is used for drawing the outline, and the current brush for filling the shape. Using a transparent brush suppresses filling. The programmer is responsible for deleting the list of points. - Note that wxWindows automatically closes the first and last points. */ void DrawPolygon(int n, wxPoint points[], wxCoord xoffset = 0, wxCoord yoffset = 0, int fill_style = wxODDEVEN_RULE); - void DrawPolygon(wxList * points, wxCoord xoffset = 0, + void DrawPolygon(wxList* points, wxCoord xoffset = 0, wxCoord yoffset = 0, int fill_style = wxODDEVEN_RULE); //@} @@ -271,8 +263,7 @@ public: wxCoord height); /** - Draws the text rotated by @e angle degrees. - + Draws the text rotated by @a angle degrees. The wxMSW wxDC and wxSVGFileDC rotate the text around slightly different points, depending on the size of the font */ @@ -284,9 +275,8 @@ public: size. The corners are quarter-circles using the given radius. The current pen is used for the outline and the current brush for filling the shape. - - If @e radius is positive, the value is assumed to be the - radius of the rounded corner. If @e radius is negative, + If @a radius is positive, the value is assumed to be the + radius of the rounded corner. If @a radius is negative, the absolute value is assumed to be the @e proportion of the smallest dimension of the rectangle. This means that the corner can be a sensible size relative to the size of the rectangle, and also avoids @@ -301,7 +291,7 @@ public: /** Draws a three-point spline using the current pen. */ - void DrawSpline(wxList * points); + void DrawSpline(wxList* points); void DrawSpline(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, wxCoord x3, @@ -311,7 +301,6 @@ public: /** Draws a text string at the specified point, using the current text font, and the current text foreground and background colours. - The coordinates refer to the top-left corner of the rectangle bounding the string. See GetTextExtent() for how to get the dimensions of a text string, which can be used to position the @@ -338,7 +327,7 @@ public: Not implemented */ void FloodFill(wxCoord x, wxCoord y, const wxColour& colour, - int style=wxFLOOD_SURFACE); + int style = wxFLOOD_SURFACE); //@{ /** @@ -352,7 +341,7 @@ public: /** Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT. - @sa wxDC::SetBackgroundMode + @see wxDC::SetBackgroundMode */ int GetBackgroundMode(); @@ -409,13 +398,13 @@ public: /** Not implemented */ - bool GetPixel(wxCoord x, wxCoord y, wxColour * colour); + bool GetPixel(wxCoord x, wxCoord y, wxColour* colour); /** For a Windows printer device context, this gets the horizontal and vertical resolution. */ - void GetSize(wxCoord * width, wxCoord * height); + void GetSize(wxCoord* width, wxCoord* height); //@{ /** @@ -427,24 +416,22 @@ public: /** Gets the dimensions of the string using the currently selected font. - @e string is the text string to measure, @e w and @e h are - the total width and height respectively, @e descent is the + @a string is the text string to measure, @a w and @a h are + the total width and height respectively, @a descent is the dimension from the baseline of the font to the bottom of the - descender, and @e externalLeading is any extra vertical space added + descender, and @a externalLeading is any extra vertical space added to the font by the font designer (usually is zero). - - The optional parameter @e font specifies an alternative + The optional parameter @a font specifies an alternative to the currently selected font: but note that this does not yet work under Windows, so you need to set a font for the device context first. - See also wxFont, SetFont(). */ - void GetTextExtent(const wxString& string, wxCoord * w, - wxCoord * h, - wxCoord * descent = @NULL, - wxCoord * externalLeading = @NULL, - wxFont * font = @NULL); + void GetTextExtent(const wxString& string, wxCoord* w, + wxCoord* h, + wxCoord* descent = NULL, + wxCoord* externalLeading = NULL, + wxFont* font = NULL); //@{ /** @@ -488,34 +475,34 @@ public: /** Gets the maximum horizontal extent used in drawing commands so far. */ -#define wxCoord MaxX() /* implementation is private */ + wxCoord MaxX(); /** Gets the maximum vertical extent used in drawing commands so far. */ -#define wxCoord MaxY() /* implementation is private */ + wxCoord MaxY(); /** Gets the minimum horizontal extent used in drawing commands so far. */ -#define wxCoord MinX() /* implementation is private */ + wxCoord MinX(); /** Gets the minimum vertical extent used in drawing commands so far. */ -#define wxCoord MinY() /* implementation is private */ + wxCoord MinY(); /** Returns @true if the DC is ok to use; False values arise from being unable to write the file */ -#define bool Ok() /* implementation is private */ + bool Ok(); /** Resets the bounding box: after a call to this function, the bounding box doesn't contain anything. - @sa wxDC::CalcBoundingBox + @see wxDC::CalcBoundingBox */ void ResetBoundingBox(); @@ -525,12 +512,11 @@ public: orientation, e.g. x axis from left to right and y axis from bottom up. @param xLeftRight - True to set the x axis orientation to the natural - left to right orientation, @false to invert it. - + True to set the x axis orientation to the natural + left to right orientation, @false to invert it. @param yBottomUp - True to set the y axis orientation to the natural - bottom up orientation, @false to invert it. + True to set the y axis orientation to the natural + bottom up orientation, @false to invert it. */ void SetAxisOrientation(bool xLeftRight, bool yBottomUp); @@ -540,20 +526,17 @@ public: void SetBackground(const wxBrush& brush); /** - @e mode may be one of wxSOLID and wxTRANSPARENT. This setting determines + @a mode may be one of wxSOLID and wxTRANSPARENT. This setting determines whether text will be drawn with a background colour or not. */ void SetBackgroundMode(int mode); /** Sets the current brush for the DC. - If the argument is wxNullBrush, the current brush is selected out of the device context, and the original brush restored, allowing the current brush to be destroyed safely. - See also wxBrush. - See also wxMemoryDC for the interpretation of colours when drawing into a monochrome bitmap. */ @@ -573,7 +556,6 @@ public: /** Sets the device origin (i.e., the origin in pixels after scaling has been applied). - This function may be useful in Windows printing operations for placing a graphic on a page. */ @@ -582,7 +564,6 @@ public: /** Sets the current font for the DC. It must be a valid font, in particular you should not pass @c wxNullFont to this method. - See also wxFont. */ void SetFont(const wxFont& font); @@ -600,40 +581,32 @@ public: wxSVGFileDC::SetUserScale) scales the text appropriately. In Windows, scaleable TrueType fonts are always used; in X, results depend on availability of fonts, but usually a reasonable match is found. - Note that the coordinate origin should ideally be selectable, but for now is always at the top left of the screen/printer. - Drawing to a Windows printer device context under UNIX uses the current mapping mode, but mapping mode is currently ignored for PostScript output. - The mapping mode can be one of the following: wxMM_TWIPS - Each logical unit is 1/20 of a point, or 1/1440 of an inch. wxMM_POINTS - Each logical unit is a point, or 1/72 of an inch. wxMM_METRIC - Each logical unit is 1 mm. wxMM_LOMETRIC - Each logical unit is 1/10 of a mm. wxMM_TEXT - Each logical unit is 1 pixel. */ void SetMapMode(int int); @@ -645,10 +618,8 @@ public: /** Sets the current pen for the DC. - If the argument is wxNullPen, the current pen is selected out of the device context, and the original pen restored. - See also wxMemoryDC for the interpretation of colours when drawing into a monochrome bitmap. */ @@ -661,7 +632,6 @@ public: /** Sets the current text foreground colour for the DC. - See also wxMemoryDC for the interpretation of colours when drawing into a monochrome bitmap. */ diff --git a/interface/dde.h b/interface/dde.h index 214aaa217a..2111e1a580 100644 --- a/interface/dde.h +++ b/interface/dde.h @@ -137,7 +137,7 @@ public: */ virtual const void* OnRequest(const wxString& topic, const wxString& item, - size_t * size, + size_t* size, wxIPCFormat format); /** @@ -177,7 +177,7 @@ public: character string (actually a pointer to the connection's buffer) if successful, @NULL otherwise. */ - const void* Request(const wxString& item, size_t * size, + const void* Request(const wxString& item, size_t* size, wxIPCFormat format = wxIPC_TEXT); /** @@ -239,22 +239,21 @@ public: the OnMakeConnection() member to return your own derived connection object. */ - wxConnectionBase * MakeConnection(const wxString& host, - const wxString& service, - const wxString& topic); + wxConnectionBase* MakeConnection(const wxString& host, + const wxString& service, + const wxString& topic); /** The type of wxDDEConnection returned from a MakeConnection() call can be altered by deriving the @b OnMakeConnection member to return your own derived connection object. By default, a wxDDEConnection object is returned. - The advantage of deriving your own connection class is that it will enable you to intercept messages initiated by the server, such as wxDDEConnection::OnAdvise. You may also want to store application-specific data in instances of the new class. */ - wxConnectionBase * OnMakeConnection(); + wxConnectionBase* OnMakeConnection(); /** Returns @true if this is a valid host name, @false otherwise. This always @@ -307,7 +306,7 @@ public: always sent for standard input and output, but in the context of DDE messages it doesn't make a lot of sense. */ - virtual wxConnectionBase * OnAcceptConnection(const wxString& topic); + virtual wxConnectionBase* OnAcceptConnection(const wxString& topic); }; @@ -319,17 +318,14 @@ public: Called when wxWidgets exits, to clean up the DDE system. This no longer needs to be called by the application. - See also wxDDEInitialize. */ void wxDDECleanUp(); /** Initializes the DDE system. May be called multiple times without harm. - This no longer needs to be called by the application: it will be called by wxWidgets if necessary. - See also wxDDEServer, wxDDEClient, wxDDEConnection, wxDDECleanUp. */ diff --git a/interface/debug.h b/interface/debug.h index 4420ad5db2..06a118f62f 100644 --- a/interface/debug.h +++ b/interface/debug.h @@ -8,33 +8,30 @@ /** Will always generate an assert error if this code is reached (in debug mode). - See also: wxFAIL_MSG */ -#define wxFAIL() /* implementation is private */ +wxFAIL(); /** This function is called whenever one of debugging macros fails (i.e. condition is @false in an assertion). It is only defined in the debug mode, in release builds the wxCHECK failures don't result in anything. - To override the default behaviour in the debug builds which is to show the user a dialog asking whether he wants to abort the program, continue or continue ignoring any subsequent assert failures, you may override wxApp::OnAssertFailure which is called by this function if the global application object exists. */ -void wxOnAssert(const char * fileName, int lineNumber, - const char * func, - const char * cond, - const char * msg = @NULL); +void wxOnAssert(const char* fileName, int lineNumber, + const char* func, + const char* cond, + const char* msg = NULL); /** In debug mode (when @c __WXDEBUG__ is defined) this function generates a debugger exception meaning that the control is passed to the debugger if one is attached to the process. Otherwise the program just terminates abnormally. - In release mode this function does nothing. */ void wxTrap(); @@ -42,12 +39,11 @@ void wxTrap(); /** Will always generate an assert error with specified message if this code is reached (in debug mode). - This macro is useful for marking unreachable" code areas, for example it may be used in the "default:" branch of a switch statement if all possible cases are processed above. - @sa wxFAIL + @see wxFAIL */ #define wxFAIL_MSG(msg) /* implementation is private */ @@ -56,14 +52,14 @@ void wxTrap(); (FAILs in debug mode). This check is done even in release mode. */ -#define wxCHECK(condition, retValue) /* implementation is private */ +#define wxCHECK(condition, retValue) /* implementation is private */ /** This macro results in a @ref overview_wxcompiletimeassert "compile time assertion failure" if the size - of the given type @e type is less than @e size bits. - + of the given type @a type is less than @a size bits. You may use it like this, for example: + @code // we rely on the int being able to hold values up to 2^32 wxASSERT_MIN_BITSIZE(int, 32); @@ -72,93 +68,86 @@ void wxTrap(); wxASSERT_MIN_BITSIZE(wchar_t, 16); @endcode */ -#define wxASSERT_MIN_BITSIZE(type, size) /* implementation is private */ +#define wxASSERT_MIN_BITSIZE(type, size) /* implementation is private */ /** Assert macro with message. An error message will be generated if the condition is @false. - @sa wxASSERT, wxCOMPILE_TIME_ASSERT + @see wxASSERT, wxCOMPILE_TIME_ASSERT */ -#define wxASSERT_MSG(condition, msg) /* implementation is private */ +#define wxASSERT_MSG(condition, msg) /* implementation is private */ /** This is the same as wxCHECK2, but - wxFAIL_MSG with the specified @e msg is called - instead of wxFAIL() if the @e condition is @false. + wxFAIL_MSG with the specified @a msg is called + instead of wxFAIL() if the @a condition is @false. */ -#define wxCHECK2(condition, operation, msg) /* implementation is private */ +#define wxCHECK2(condition, operation, msg) /* implementation is private */ /** Assert macro. An error message will be generated if the condition is @false in debug mode, but nothing will be done in the release build. - Please note that the condition in wxASSERT() should have no side effects because it will not be executed in release mode at all. - @sa wxASSERT_MSG, wxCOMPILE_TIME_ASSERT + @see wxASSERT_MSG, wxCOMPILE_TIME_ASSERT */ #define wxASSERT(condition) /* implementation is private */ /** Checks that the condition is @true, and returns if not (FAILs with given error message in debug mode). This check is done even in release mode. - This macro should be used in void functions instead of wxCHECK_MSG. */ -#define wxCHECK_RET(condition, msg) /* implementation is private */ +#define wxCHECK_RET(condition, msg) /* implementation is private */ /** Checks that the condition is @true and wxFAIL and execute - @e operation if it is not. This is a generalisation of + @a operation if it is not. This is a generalisation of wxCHECK and may be used when something else than just - returning from the function must be done when the @e condition is @false. - + returning from the function must be done when the @a condition is @false. This check is done even in release mode. */ -#define wxCHECK2(condition, operation) /* implementation is private */ +#define wxCHECK2(condition, operation) /* implementation is private */ /** This macro is identical to wxCOMPILE_TIME_ASSERT2 - except that it allows you to specify a unique @e name for the struct + except that it allows you to specify a unique @a name for the struct internally defined by this macro to avoid getting the compilation errors described above. */ -#define wxCOMPILE_TIME_ASSERT(condition, msg, name) /* implementation is private */ +#define wxCOMPILE_TIME_ASSERT(condition, msg, name) /* implementation is private */ /** Checks that the condition is @true, returns with the given return value if not (FAILs in debug mode). This check is done even in release mode. - This macro may be only used in non-void functions, see also wxCHECK_RET. */ -#define wxCHECK_MSG(condition, retValue, msg) /* implementation is private */ +#define wxCHECK_MSG(condition, retValue, msg) /* implementation is private */ /** Using @c wxCOMPILE_TIME_ASSERT results in a compilation error if the - specified @e condition is @false. The compiler error message should include - the @e msg identifier - please note that it must be a valid C++ identifier + specified @a condition is @false. The compiler error message should include + the @a msg identifier - please note that it must be a valid C++ identifier and not a string unlike in the other cases. - This macro is mostly useful for testing the expressions involving the @c sizeof operator as they can't be tested by the preprocessor but it is sometimes desirable to test them at the compile time. - Note that this macro internally declares a struct whose name it tries to make unique by using the @c __LINE__ in it but it may still not work if you use it on the same line in two different source files. In this case you may either change the line in which either of them appears on or use the wxCOMPILE_TIME_ASSERT2 macro. - Also note that Microsoft Visual C++ has a bug which results in compiler errors if you use this macro with 'Program Database For Edit And Continue' (@c /ZI) option, so you shouldn't use it ('Program Database' (@c /Zi) is ok though) for the code making use of this macro. - @sa wxASSERT_MSG, wxASSERT_MIN_BITSIZE + @see wxASSERT_MSG, wxASSERT_MIN_BITSIZE */ -#define wxCOMPILE_TIME_ASSERT(condition, msg) /* implementation is private */ +#define wxCOMPILE_TIME_ASSERT(condition, msg) /* implementation is private */ diff --git a/interface/debugrpt.h b/interface/debugrpt.h index bdb44b9922..3480b5c88e 100644 --- a/interface/debugrpt.h +++ b/interface/debugrpt.h @@ -144,7 +144,6 @@ public: /** Adds the minidump file to the debug report. - Minidumps are only available under recent Win32 versions (@c dbghlp32.dll can be installed under older systems to make minidumps available). */ @@ -161,11 +160,10 @@ public: bool AddExceptionDump(); /** - Add another file to the report. If @e filename is an absolute path, it is + Add another file to the report. If @a filename is an absolute path, it is copied to a file in the debug report directory with the same name. Otherwise the file should already exist in this directory - - @e description only exists to be displayed to the user in the report summary + @a description only exists to be displayed to the user in the report summary shown by wxDebugReportPreview. */ void AddFile(const wxString& filename, @@ -173,9 +171,8 @@ public: /** This is a convenient wrapper around AddFile(). It - creates the file with the given @e name and writes @e text to it, then - adds the file to the report. The @e filename shouldn't contain the path. - + creates the file with the given @e name and writes @a text to it, then + adds the file to the report. The @a filename shouldn't contain the path. Returns @true if file could be added successfully, @false if an IO error occurred. */ @@ -187,7 +184,7 @@ public: context file created by AddContext(). By default, it does nothing. */ - void DoAddCustomContext(wxXmlNode * nodeRoot); + void DoAddCustomContext(wxXmlNode* nodeRoot); /** This function may be overridden to modify the contents of the exception tag in @@ -209,7 +206,6 @@ public: /** Returns the name of the temporary directory used for the files in this report. - This method should be used to construct the full name of the files which you wish to add to the report using AddFile(). */ @@ -218,7 +214,7 @@ public: /** Retrieves the name (relative to wxDebugReport::GetDirectory) and the description of the - file with the given index. If @e n is greater than or equal to the number of + file with the given index. If @a n is greater than or equal to the number of filse, @false is returned. */ bool GetFile(size_t n, wxString* name, wxString* desc); @@ -239,7 +235,7 @@ public: returns @false the report can't be used. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** Processes this report: the base class simply notifies the user that the @@ -307,11 +303,10 @@ class wxDebugReportUpload : public wxDebugReportCompress public: /** ) - This class will upload the compressed file created by its base class to an HTML - multipart/form-data form at the specified address. The @e url is the upload - page address, @e input is the name of the @c "type=file" control on - the form used for the file name and @e action is the value of the form + multipart/form-data form at the specified address. The @a url is the upload + page address, @a input is the name of the @c "type=file" control on + the form used for the file name and @a action is the value of the form action field. The report is uploaded using @c @e curl program which should be available, the @e curl parameter may be used to specify the full path to it. @@ -321,7 +316,6 @@ public: /** ) - This function may be overridden in a derived class to show the output from curl: this may be an HTML page or anything else that the server returned. Value returned by this function becomes the return value of diff --git a/interface/defs.h b/interface/defs.h index 2f6dcf212b..972f52c6be 100644 --- a/interface/defs.h +++ b/interface/defs.h @@ -8,7 +8,7 @@ //@{ /** - These macros will swap the bytes of the @e value variable from little + These macros will swap the bytes of the @a value variable from little endian to big endian or vice versa unconditionally, i.e. independently of the current platform. */ @@ -21,11 +21,10 @@ wxUint16 wxUINT16_SWAP_ALWAYS(wxUint16 value); //@{ /** - This macro will swap the bytes of the @e value variable from little + This macro will swap the bytes of the @a value variable from little endian to big endian or vice versa if the program is compiled on a little-endian architecture (such as Intel PCs). If the program has been compiled on a big-endian architecture, the value will be unchanged. - Use these macros to read data from and write data to a file that stores data in big-endian format. */ @@ -37,9 +36,8 @@ wxUint16 wxUINT16_SWAP_ON_LE(wxUint16 value); /** This macro is similar to wxDEPRECATED but can be used - to not only declare the function @e func as deprecated but to also provide + to not only declare the function @a func as deprecated but to also provide its (inline) implementation @e body. - It can be used as following: @code @@ -52,7 +50,7 @@ wxUint16 wxUINT16_SWAP_ON_LE(wxUint16 value); }; @endcode */ -#define wxDEPRECATED_INLINE(func, body) /* implementation is private */ +#define wxDEPRECATED_INLINE(func, body) /* implementation is private */ /** @c wxEXPLICIT is a macro which expands to the C++ @c explicit keyword if @@ -67,9 +65,10 @@ wxUint16 wxUINT16_SWAP_ON_LE(wxUint16 value); unless it has a friend. This warning may sometimes be useful but it doesn't make sense for reference counted class which always delete themselves (hence destructor should be private) but don't necessarily have any friends, so this - macro is provided to disable the warning in such case. The @e name parameter + macro is provided to disable the warning in such case. The @a name parameter should be the name of the class but is only used to construct a unique friend class name internally. Example of using the macro: + @code class RefCounted { @@ -91,11 +90,10 @@ wxUint16 wxUINT16_SWAP_ON_LE(wxUint16 value); //@{ /** - This macro will swap the bytes of the @e value variable from little + This macro will swap the bytes of the @a value variable from little endian to big endian or vice versa if the program is compiled on a big-endian architecture (such as Sun work stations). If the program has been compiled on a little-endian architecture, the value will be unchanged. - Use these macros to read data from and write data to a file that stores data in little-endian (for example Intel i386) format. */ @@ -110,7 +108,6 @@ wxUint16 wxUINT16_SWAP_ON_BE(wxUint16 value); indicating that this function is deprecated (i.e. obsolete and planned to be removed in the future) when it is used. Only Visual C++ 7 and higher and g++ compilers currently support this functionality. - Example of use: @code @@ -128,7 +125,6 @@ wxUint16 wxUINT16_SWAP_ON_BE(wxUint16 value); which support it or its replacement for those that don't. It must be used to preserve the value of a @c va_list object if you need to use it after passing it to another function because it can be modified by the latter. - As with @c va_start, each call to @c wxVaCopy must have a matching @c va_end. */ diff --git a/interface/dialog.h b/interface/dialog.h index 0353e0ba41..c84301bc3a 100644 --- a/interface/dialog.h +++ b/interface/dialog.h @@ -61,8 +61,8 @@ @category{cmndlg} @seealso - @ref overview_wxdialogoverview "wxDialog overview", wxFrame, @ref - overview_validatoroverview "Validator overview" + @ref overview_wxdialogoverview, wxFrame, @ref overview_validatoroverview + "Validator overview" */ class wxDialog : public wxTopLevelWindow { @@ -72,31 +72,26 @@ public: Constructor. @param parent - Can be @NULL, a frame or another dialog box. - + Can be @NULL, a frame or another dialog box. @param id - An identifier for the dialog. A value of -1 is taken to mean a default. - + An identifier for the dialog. A value of -1 is taken to mean a default. @param title - The title of the dialog. - + The title of the dialog. @param pos - The dialog position. The value wxDefaultPosition indicates a default position, chosen by - either the windowing system or wxWidgets, depending on platform. - + The dialog position. The value wxDefaultPosition indicates a default position, + chosen by + either the windowing system or wxWidgets, depending on platform. @param size - The dialog size. The value wxDefaultSize indicates a default size, chosen by - either the windowing system or wxWidgets, depending on platform. - + The dialog size. The value wxDefaultSize indicates a default size, chosen by + either the windowing system or wxWidgets, depending on platform. @param style - The window style. See wxDialog. - + The window style. See wxDialog. @param name - Used to associate a name with the window, - allowing the application user to set Motif resource values for - individual dialog boxes. + Used to associate a name with the window, + allowing the application user to set Motif resource values for + individual dialog boxes. - @sa Create() + @see Create() */ wxDialog(); wxDialog(wxWindow* parent, wxWindowID id, @@ -115,7 +110,6 @@ public: /** Adds an identifier to be regarded as a main button for the non-scrolling area of a dialog. - See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for more on layout adaptation. */ @@ -125,7 +119,6 @@ public: Returns @true if this dialog can and should perform layout adaptation using DoLayoutAdaptation(), usually if the dialog is too large to fit on the display. - See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for more on layout adaptation. */ @@ -135,7 +128,7 @@ public: Centres the dialog box on the display. @param direction - May be wxHORIZONTAL, wxVERTICAL or wxBOTH. + May be wxHORIZONTAL, wxVERTICAL or wxBOTH. */ void Centre(int direction = wxBOTH); @@ -151,12 +144,10 @@ public: const wxString& name = "dialogBox"); /** - Creates a sizer with standard buttons. @e flags is a bit list + Creates a sizer with standard buttons. @a flags is a bit list of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, wxCLOSE, wxHELP, wxNO_DEFAULT. - The sizer lays out the buttons in a manner appropriate to the platform. - This function uses CreateStdDialogButtonSizer() internally for most platforms but doesn't create the sizer at all for the platforms with hardware buttons (such as smartphones) for which it sets up the @@ -169,7 +160,6 @@ public: Creates a sizer with standard buttons using CreateButtonSizer() separated from the rest of the dialog contents by a horizontal wxStaticLine. - Please notice that just like CreateButtonSizer() this function may return @c @NULL if no buttons were created. @@ -177,10 +167,9 @@ public: wxSizer* CreateSeparatedButtonSizer(long flags); /** - Creates a wxStdDialogButtonSizer with standard buttons. @e flags is a bit list + Creates a wxStdDialogButtonSizer with standard buttons. @a flags is a bit list of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, wxCLOSE, wxHELP, wxNO_DEFAULT. - The sizer lays out the buttons in a manner appropriate to the platform. */ wxStdDialogButtonSizer* CreateStdDialogButtonSizer(long flags); @@ -188,7 +177,6 @@ public: /** Performs layout adaptation, usually if the dialog is too large to fit on the display. - See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for more on layout adaptation. */ @@ -201,11 +189,10 @@ public: wxWidgets will call Close() for the dialog. */ -#define virtual bool DoOK() /* implementation is private */ + virtual bool DoOK(); /** A static function enabling or disabling layout adaptation for all dialogs. - See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for more on layout adaptation. */ @@ -216,9 +203,9 @@ public: invocation. @param retCode - The value that should be returned by ShowModal. + The value that should be returned by ShowModal. - @sa ShowModal(), GetReturnCode(), SetReturnCode() + @see ShowModal(), GetReturnCode(), SetReturnCode() */ void EndModal(int retCode); @@ -226,7 +213,7 @@ public: Gets the identifier of the button which works like standard OK button in this dialog. - @sa SetAffirmativeId() + @see SetAffirmativeId() */ int GetAffirmativeId(); @@ -244,14 +231,13 @@ public: Gets the identifier of the button to map presses of @c ESC button to. - @sa SetEscapeId() + @see SetEscapeId() */ int GetEscapeId(); /** Returns @true if the dialog has been adapted, usually by making it scrollable to work with a small display. - See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for more on layout adaptation. */ @@ -262,7 +248,6 @@ public: to be in the non-scrolling part of a layout-adapted dialog. Zero switches off adaptation, and 3 allows search for standard buttons anywhere in the dialog. - See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for more on layout adaptation. */ @@ -270,7 +255,6 @@ public: /** Gets the adaptation mode, overriding the global adaptation flag. - See also SetLayoutAdaptationMode() and @ref overview_autoscrollingdialogs "Automatic scrolling dialogs". */ @@ -278,7 +262,6 @@ public: /** A static function getting the current layout adapter object. - See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for more on layout adaptation. */ @@ -287,7 +270,6 @@ public: /** Returns an array of identifiers to be regarded as the main buttons for the non-scrolling area of a dialog. - See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for more on layout adaptation. */ @@ -297,9 +279,9 @@ public: Gets the return code for this window. @remarks A return code is normally associated with a modal dialog, where - ShowModal() returns a code to the application. + ShowModal() returns a code to the application. - @sa SetReturnCode(), ShowModal(), EndModal() + @see SetReturnCode(), ShowModal(), EndModal() */ int GetReturnCode(); @@ -308,7 +290,6 @@ public: GetToolBar allows you to access the toolbar and add tools to it. Removing tools and adding arbitrary controls are not currently supported. - This function is not available on any other platform. */ wxToolBar* GetToolBar(); @@ -317,14 +298,14 @@ public: Iconizes or restores the dialog. Windows only. @param iconize - If @true, iconizes the dialog box; if @false, shows and restores it. + If @true, iconizes the dialog box; if @false, shows and restores it. @remarks Note that in Windows, iconization has no effect since dialog - boxes cannot be iconized. However, applications may - need to explicitly restore dialog boxes under Motif - which have user-iconizable frames, and under Windows - calling Iconize(@false) will bring the window to the - front, as does Show(@true). + boxes cannot be iconized. However, applications may + need to explicitly restore dialog boxes under Motif + which have user-iconizable frames, and under Windows + calling Iconize(@false) will bring the window to the + front, as does Show(@true). */ void Iconize(bool iconize); @@ -332,23 +313,21 @@ public: Returns @true if the dialog box is iconized. Windows only. @remarks Always returns @false under Windows since dialogs cannot be - iconized. + iconized. */ bool IsIconized(); /** A static function returning @true if layout adaptation is enabled for all dialogs. - See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for more on layout adaptation. */ static bool IsLayoutAdaptationEnabled(); /** - Returns @true if @e id is in the array of identifiers to be regarded as the + Returns @true if @a id is in the array of identifiers to be regarded as the main buttons for the non-scrolling area of a dialog. - See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for more on layout adaptation. */ @@ -363,17 +342,17 @@ public: The default handler for wxEVT_SYS_COLOUR_CHANGED. @param event - The colour change event. + The colour change event. @remarks Changes the dialog's colour to conform to the current settings - (Windows only). Add an event table entry for your - dialog class if you wish the behaviour to be - different (such as keeping a user-defined background - colour). If you do override this function, call - wxEvent::Skip to propagate the notification to child - windows and controls. + (Windows only). Add an event table entry for your + dialog class if you wish the behaviour to be different + (such as keeping a user-defined background colour). If + you do override this function, call wxEvent::Skip to + propagate the notification to child windows and + controls. - @sa wxSysColourChangedEvent + @see wxSysColourChangedEvent */ void OnSysColourChanged(wxSysColourChangedEvent& event); @@ -383,14 +362,12 @@ public: and wxWindow::TransferDataFromWindow and, if they both return @true, closes the dialog with @c wxID_OK return code. - Also, when the user presses a hardware OK button on the devices having one or the special OK button in the PocketPC title bar, an event with this id is generated. - By default, the affirmative id is wxID_OK. - @sa GetAffirmativeId(), SetEscapeId() + @see GetAffirmativeId(), SetEscapeId() */ void SetAffirmativeId(int id); @@ -400,11 +377,10 @@ public: clicked, the dialog is closed. Also, when the user presses @c ESC key in the dialog or closes the dialog using the close button in the title bar, this is mapped to the click of the button with the specified id. - By default, the escape id is the special value @c wxID_ANY meaning that @c wxID_CANCEL button is used if it's present in the dialog and otherwise the button with GetAffirmativeId() - is used. Another special value for @e id is @c wxID_NONE meaning that + is used. Another special value for @a id is @c wxID_NONE meaning that @c ESC presses should be ignored. If any other value is given, it is interpreted as the id of the button to map the escape key to. */ @@ -414,7 +390,7 @@ public: Sets the icon for this dialog. @param icon - The icon to associate with this dialog. + The icon to associate with this dialog. */ void SetIcon(const wxIcon& icon); @@ -422,14 +398,13 @@ public: Sets the icons for this dialog. @param icons - The icons to associate with this dialog. + The icons to associate with this dialog. */ void SetIcons(const wxIconBundle& icons); /** Marks the dialog as having been adapted, usually by making it scrollable to work with a small display. - See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for more on layout adaptation. */ @@ -440,15 +415,15 @@ public: non-scrolling part of a layout-adapted dialog. Zero switches off adaptation, and 3 allows search for standard buttons anywhere in the dialog. - See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for more on layout adaptation. */ void SetLayoutAdaptationLevel(int level); /** - Sets the adaptation mode, overriding the global adaptation flag. @e mode may be + Sets the adaptation mode, overriding the global adaptation flag. @a mode may be one of the following values: + See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for more on layout adaptation. */ @@ -458,7 +433,6 @@ public: A static function for setting the current layout adapter object, returning the old adapter. If you call this, you should delete the old adapter object. - See also wxDialogLayoutAdapter and @ref overview_autoscrollingdialogs "Automatic scrolling dialogs". */ @@ -467,13 +441,12 @@ public: /** @b NB: 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 until the dialog is hidden) or modeless (control returns immediately). @param flag - If @true, the dialog will be modal, otherwise it will be modeless. + If @true, the dialog will be modal, otherwise it will be modeless. */ void SetModal(bool flag); @@ -481,14 +454,13 @@ public: Sets the return code for this window. @param retCode - The integer return code, usually a control identifier. + The integer return code, usually a control identifier. @remarks A return code is normally associated with a modal dialog, where - ShowModal() returns a code to the - application. The function EndModal() calls - SetReturnCode. + ShowModal() returns a code to the application. + The function EndModal() calls SetReturnCode. - @sa GetReturnCode(), ShowModal(), EndModal() + @see GetReturnCode(), ShowModal(), EndModal() */ void SetReturnCode(int retCode); @@ -496,12 +468,12 @@ public: Hides or shows the dialog. @param show - If @true, the dialog box is shown and brought to the front; - otherwise the box is hidden. If @false and the dialog is - modal, control is returned to the calling program. + If @true, the dialog box is shown and brought to the front; + otherwise the box is hidden. If @false and the dialog is + modal, control is returned to the calling program. @remarks The preferred way of dismissing a modal dialog is to use - EndModal(). + EndModal(). */ bool Show(bool show); diff --git a/interface/dialup.h b/interface/dialup.h index 541a3f3c54..87b921f968 100644 --- a/interface/dialup.h +++ b/interface/dialup.h @@ -43,10 +43,9 @@ public: /** Cancel dialing the number initiated with Dial() with async parameter equal to @true. - Note that this won't result in DISCONNECTED event being sent. - @sa IsDialing() + @see IsDialing() */ bool CancelDialing(); @@ -58,28 +57,24 @@ public: wxDialUpManager* Create(); /** - Dial the given ISP, use @e username and @e password to authenticate. - + Dial the given ISP, use @a username and @a password to authenticate. The parameters are only used under Windows currently, for Unix you should use SetConnectCommand() to customize this functions behaviour. - - If no @e nameOfISP is given, the function will select the default one + If no @a nameOfISP is given, the function will select the default one (proposing the user to choose among all connections defined on this machine) and if no username and/or password are given, the function will try to do without them, but will ask the user if really needed. - - If @e async parameter is @false, the function waits until the end of dialing + If @a async parameter is @false, the function waits until the end of dialing and returns @true upon successful completion. - - If @e async is @true, the function only initiates the connection and + If @a async is @true, the function only initiates the connection and returns immediately - the result is reported via events (an event is sent anyhow, but if dialing failed it will be a DISCONNECTED one). */ bool Dial(const wxString& nameOfISP = wxEmptyString, const wxString& username = wxEmptyString, const wxString& password = wxEmptyString, - bool async = @true); + bool async = true); /** Disable automatic check for connection status change - notice that the @@ -94,14 +89,12 @@ public: often should we repeat the check (each minute by default). Under Windows, the notification about the change of connection status is sent by the system and so we don't do any polling and this parameter is ignored. - Returns @false if couldn't set up automatic check for online status. */ bool EnableAutoCheckOnlineStatus(size_t nSeconds = 60); /** This function is only implemented under Windows. - Fills the array with the names of all possible values for the first parameter to Dial() on this machine and returns their number (may be 0). @@ -116,7 +109,6 @@ 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 guaranteed to be correct, so it is better to ask user for confirmation or give him a possibility to override it. @@ -126,7 +118,7 @@ public: /** Returns @true if (async) dialing is in progress. - @sa Dial() + @see Dial() */ bool IsDialing(); @@ -136,7 +128,7 @@ public: good idea to call this function and check its result before calling any other wxDialUpManager methods */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** Returns @true if the computer is connected to the network: under Windows, @@ -148,9 +140,7 @@ public: /** , @b const wxString&@e commandHangup = wxT("/usr/bin/poff")) - This method is for Unix only. - Sets the commands to start up the network and to hang up again. */ void SetConnectCommand(); @@ -161,13 +151,12 @@ public: allows to forcefully set the online status - whatever our internal algorithm may think about it. - @sa IsOnline() + @see IsOnline() */ - void SetOnlineStatus(bool isOnline = @true); + void SetOnlineStatus(bool isOnline = true); /** This method is for Unix only. - Under Unix, the value of well-known host is used to check whether we're connected to the internet. It is unused under Windows, but this function is always safe to call. The default value is @c www.yahoo.com:80. diff --git a/interface/dir.h b/interface/dir.h index cbcda9bb60..5f7bd2000d 100644 --- a/interface/dir.h +++ b/interface/dir.h @@ -55,7 +55,6 @@ public: to abort traversing completely, @c wxDIR_IGNORE to skip this directory but continue with others or @c wxDIR_CONTINUE to enumerate all files and subdirectories in this directory. - This is a pure virtual function and must be implemented in the derived class. */ virtual wxDirTraverseResult OnDir(const wxString& dirname); @@ -64,7 +63,6 @@ public: This function is called for each file. It may return @c wxDIR_STOP to abort traversing (for example, if the file being searched is found) or @c wxDIR_CONTINUE to proceed. - This is a pure virtual function and must be implemented in the derived class. */ virtual wxDirTraverseResult OnFile(const wxString& filename); @@ -74,7 +72,6 @@ public: enumerating. It may return @c wxSIR_STOP to abort traversing completely, @c wxDIR_IGNORE to skip this directory but continue with others or @c wxDIR_CONTINUE to retry opening this directory once again. - The base class version always returns @c wxDIR_IGNORE. */ virtual wxDirTraverseResult OnOpenError(const wxString& openerrorname); @@ -147,13 +144,11 @@ public: /** The function returns the path of the first file matching the given @e filespec or an empty string if there are no files matching it. - - The @e flags parameter may or may not include @c wxDIR_FILES, the - function always behaves as if it were specified. By default, @e flags + The @a flags parameter may or may not include @c wxDIR_FILES, the + function always behaves as if it were specified. By default, @a flags includes @c wxDIR_DIRS and so the function recurses into the subdirectories but if this flag is not specified, the function restricts the search only to - the directory @e dirname itself. - + the directory @a dirname itself. See also: Traverse() */ static wxString FindFirst(const wxString& dirname, @@ -161,23 +156,21 @@ public: int flags = wxDIR_DEFAULT); /** - The function appends the names of all the files under directory @e dirname - to the array @e files (note that its old content is preserved). Only files - matching the @e filespec are taken, with empty spec matching all the files. - - The @e flags parameter should always include @c wxDIR_FILES or the array + The function appends the names of all the files under directory @a dirname + to the array @a files (note that its old content is preserved). Only files + matching the @a filespec are taken, with empty spec matching all the files. + The @a flags parameter should always include @c wxDIR_FILES or the array would be unchanged and should include @c wxDIR_DIRS flag to recurse into subdirectories (both flags are included in the value by default). - See also: Traverse() */ static size_t GetAllFiles(const wxString& dirname, - wxArrayString * files, + wxArrayString* files, const wxString& filespec = wxEmptyString, int flags = wxDIR_DEFAULT); /** - Start enumerating all files matching @e filespec (or all files if it is + Start enumerating all files matching @a filespec (or all files if it is empty) and @e flags, return @true on success. */ bool GetFirst(wxString* filename, @@ -199,7 +192,6 @@ public: /** Returns the size (in bytes) of all files recursively found in @c dir or @c wxInvalidSize in case of error. - In case it happens that while traversing folders a file's size can not be read, that file is added to the @c filesSkipped array, if not @NULL, and then skipped. @@ -210,16 +202,15 @@ public: then the returned value is not 100% accurate and, if the skipped files were big, it could be far from real size of the directory. - See also: wxFileName::GetHumanReadableSize, wxGetDiskSpace */ static wxULongLong GetTotalSize(const wxString& dir, - wxArrayString* filesSkipped = @NULL); + wxArrayString* filesSkipped = NULL); /** Returns @true if the directory contains any files matching the given - @e filespec. If @e filespec is empty, look for any files at all. In any + @e filespec. If @a filespec is empty, look for any files at all. In any case, even hidden files are taken into account. */ bool HasFiles(const wxString& filespec = wxEmptyString); @@ -247,19 +238,15 @@ public: Enumerate all files and directories under the given directory recursively calling the element of the provided wxDirTraverser object for each of them. - More precisely, the function will really recurse into subdirectories if - @e flags contains @c wxDIR_DIRS flag. It will ignore the files (but + @a flags contains @c wxDIR_DIRS flag. It will ignore the files (but still possibly recurse into subdirectories) if @c wxDIR_FILES flag is given. - For each found directory, @ref wxDirTraverser::ondir sink.OnDir is called and @ref wxDirTraverser::onfile sink.OnFile is called for every file. Depending on the return value, the enumeration may continue or stop. - The function returns the total number of files found or @c (size_t)-1 on error. - See also: GetAllFiles() */ size_t Traverse(wxDirTraverser& sink, diff --git a/interface/dirctrl.h b/interface/dirctrl.h index 80ef780c2a..5292f983bc 100644 --- a/interface/dirctrl.h +++ b/interface/dirctrl.h @@ -28,35 +28,26 @@ public: Main constructor. @param parent - Parent window. - + Parent window. @param id - Window identifier. - + Window identifier. @param dir - Initial folder. - + Initial folder. @param pos - Position. - + Position. @param size - Size. - + Size. @param style - Window style. Please see wxGenericDirCtrl for a list of possible styles. - + Window style. Please see wxGenericDirCtrl for a list of possible styles. @param filter - A filter string, using the same syntax as that for wxFileDialog. This may be - empty if filters - are not being used. - - Example: "All files (*.*)|*.*|JPEG files (*.jpg)|*.jpg" - + A filter string, using the same syntax as that for wxFileDialog. This may + be empty if filters + are not being used. + Example: "All files (*.*)|*.*|JPEG files (*.jpg)|*.jpg" @param defaultFilter - The zero-indexed default filter setting. - + The zero-indexed default filter setting. @param name - The window name. + The window name. */ wxGenericDirCtrl(); wxGenericDirCtrl(wxWindow* parent, const wxWindowID id = -1, @@ -109,7 +100,6 @@ public: /** Gets selected filename path only (else empty string). - This function doesn't count a directory as a selection. */ wxString GetFilePath(); @@ -177,8 +167,8 @@ public: /** @param show - If @true, hidden folders and files will be displayed by the - control. If @false, they will not be displayed. + If @true, hidden folders and files will be displayed by the + control. If @false, they will not be displayed. */ void ShowHidden(bool show); }; diff --git a/interface/dirdlg.h b/interface/dirdlg.h index 58050c57a2..06f049237b 100644 --- a/interface/dirdlg.h +++ b/interface/dirdlg.h @@ -40,25 +40,19 @@ public: the dialog. @param parent - Parent window. - + Parent window. @param message - Message to show on the dialog. - + Message to show on the dialog. @param defaultPath - The default path, or the empty string. - + The default path, or the empty string. @param style - The dialog style. See wxDirDialog - + The dialog style. See wxDirDialog @param pos - Dialog position. Ignored under Windows. - + Dialog position. Ignored under Windows. @param size - Dialog size. Ignored under Windows. - + Dialog size. Ignored under Windows. @param name - The dialog name, not used. + The dialog name, not used. */ wxDirDialog(wxWindow* parent, const wxString& message = "Choose a directory", @@ -109,9 +103,9 @@ public: Pops up a directory selector dialog. The arguments have the same meaning as those of wxDirDialog::wxDirDialog(). The message is displayed at the top, and the default_path, if specified, is set as the initial selection. - The application must check for an empty return value (if the user pressed Cancel). For example: + @code const wxString& dir = wxDirSelector("Choose a folder"); if ( !dir.empty() ) @@ -124,5 +118,5 @@ wxString wxDirSelector(const wxString& message = wxDirSelectorPromptStr, const wxString& default_path = "", long style = 0, const wxPoint& pos = wxDefaultPosition, - wxWindow * parent = @NULL); + wxWindow* parent = NULL); diff --git a/interface/display.h b/interface/display.h index fb9d8a784a..14060218da 100644 --- a/interface/display.h +++ b/interface/display.h @@ -25,8 +25,8 @@ public: Constructor, setting up a wxDisplay instance with the specified display. @param index - The index of the display to use. This must be non-negative - and lower than the value returned by GetCount(). + The index of the display to use. This must be non-negative + and lower than the value returned by GetCount(). */ wxDisplay(unsigned index = 0); @@ -38,14 +38,12 @@ public: /** Changes the video mode of this display to the mode specified in the mode parameter. - If wxDefaultVideoMode is passed in as the mode parameter, the defined behaviour is that wxDisplay will reset the video mode to the default mode used by the display. On Windows, the behavior is normal. However, there are differences on other platforms. On Unix variations using X11 extensions it should behave as defined, but some irregularities may occur. - On wxMac passing in wxDefaultVideoMode as the mode parameter does nothing. This happens because carbon no longer has access to DMUseScreenPrefs, an undocumented @@ -82,20 +80,18 @@ public: @c wxNOT_FOUND if the point is not on any connected display. @param pt - The point to locate. + The point to locate. */ static int GetFromPoint(const wxPoint& pt); /** Returns the index of the display on which the given window lies. - If the window is on more than one display it gets the display that overlaps the window the most. - Returns @c wxNOT_FOUND if the window is not on any connected display. @param win - The window to locate. + The window to locate. */ static int GetFromWindow(const wxWindow* win); diff --git a/interface/dnd.h b/interface/dnd.h index 89ebeb8ce7..f92bbe4c3b 100644 --- a/interface/dnd.h +++ b/interface/dnd.h @@ -16,8 +16,7 @@ @category{dnd} @seealso - @ref overview_wxdndoverview "Drag and drop overview", wxDropSource, - wxDropTarget, wxFileDropTarget + @ref overview_wxdndoverview, wxDropSource, wxDropTarget, wxFileDropTarget */ class wxTextDropTarget : public wxDropTarget { @@ -37,13 +36,11 @@ public: Override this function to receive dropped text. @param x - The x coordinate of the mouse. - + The x coordinate of the mouse. @param y - The y coordinate of the mouse. - + The y coordinate of the mouse. @param data - The data being dropped: a wxString. + The data being dropped: a wxString. */ virtual bool OnDropText(wxCoord x, wxCoord y, const wxString& data); @@ -70,8 +67,7 @@ public: wxDropTarget::OnEnter, possibly many times wxDropTarget::OnDragOver, wxDropTarget::OnDrop and finally wxDropTarget::OnData. - See @ref overview_wxdndoverview "Drag and drop overview" and @ref - overview_wxdataobjectoverview "wxDataObject overview" + See @ref overview_wxdndoverview and @ref overview_wxdataobjectoverview for more information. @library{wxcore} @@ -84,9 +80,9 @@ class wxDropTarget { public: /** - Constructor. @e data is the data to be associated with the drop target. + Constructor. @a data is the data to be associated with the drop target. */ - wxDropTarget(wxDataObject* data = @NULL); + wxDropTarget(wxDataObject* data = NULL); /** Destructor. Deletes the associated data object, if any. @@ -114,17 +110,15 @@ public: this calls functions return the suggested return value @e def. @param x - The x coordinate of the mouse. - + The x coordinate of the mouse. @param y - The y coordinate of the mouse. - + The y coordinate of the mouse. @param def - Suggested value for return value. Determined by SHIFT or CONTROL key states. + Suggested value for return value. Determined by SHIFT or CONTROL key states. @returns Returns the desired operation or wxDragNone. This is used for - optical feedback from the side of the drop source, - typically in form of changing the icon. + optical feedback from the side of the drop source, + typically in form of changing the icon. */ virtual wxDragResult OnDragOver(wxCoord x, wxCoord y, wxDragResult def); @@ -134,10 +128,9 @@ public: the operation. @param x - The x coordinate of the mouse. - + The x coordinate of the mouse. @param y - The y coordinate of the mouse. + The y coordinate of the mouse. @returns Return @true to accept the data, @false to veto the operation. */ @@ -148,17 +141,16 @@ public: OnDragOver(). @param x - The x coordinate of the mouse. - + The x coordinate of the mouse. @param y - The y coordinate of the mouse. - + The y coordinate of the mouse. @param def - Suggested default for return value. Determined by SHIFT or CONTROL key states. + Suggested default for return value. Determined by SHIFT or CONTROL key + states. @returns Returns the desired operation or wxDragNone. This is used for - optical feedback from the side of the drop source, - typically in form of changing the icon. + optical feedback from the side of the drop source, + typically in form of changing the icon. */ virtual wxDragResult OnEnter(wxCoord x, wxCoord y, wxDragResult def); @@ -182,8 +174,7 @@ public: This class represents a source for a drag and drop operation. - See @ref overview_wxdndoverview "Drag and drop overview" and @ref - overview_wxdataobjectoverview "wxDataObject overview" + See @ref overview_wxdndoverview and @ref overview_wxdataobjectoverview for more information. @library{wxcore} @@ -198,32 +189,27 @@ public: //@{ /** The constructors for wxDataObject. - - If you use the constructor without @e data parameter you must call + If you use the constructor without @a data parameter you must call SetData() later. - - Note that the exact type of @e iconCopy and subsequent parameters differs + Note that the exact type of @a iconCopy and subsequent parameters differs between wxMSW and wxGTK: these are cursors under Windows but icons for GTK. You should use the macro wxDROP_ICON in portable programs instead of directly using either of these types. @param win - The window which initiates the drag and drop operation. - + The window which initiates the drag and drop operation. @param iconCopy - The icon or cursor used for feedback for copy operation. - + The icon or cursor used for feedback for copy operation. @param iconMove - The icon or cursor used for feedback for move operation. - + The icon or cursor used for feedback for move operation. @param iconNone - The icon or cursor used for feedback when operation can't be done. + The icon or cursor used for feedback when operation can't be done. */ - wxDropSource(wxWindow* win = @NULL, + wxDropSource(wxWindow* win = NULL, const wxIconOrCursor& iconCopy = wxNullIconOrCursor, const wxIconOrCursor& iconMove = wxNullIconOrCursor, const wxIconOrCursor& iconNone = wxNullIconOrCursor); - wxDropSource(wxDataObject& data, wxWindow* win = @NULL, + wxDropSource(wxDataObject& data, wxWindow* win = NULL, const wxIconOrCursor& iconCopy = wxNullIconOrCursor, const wxIconOrCursor& iconMove = wxNullIconOrCursor, const wxIconOrCursor& iconNone = wxNullIconOrCursor); @@ -240,21 +226,21 @@ public: mouse. @param flags - If wxDrag_AllowMove is included in the flags, data may - be moved and not only copied (default). If wxDrag_DefaultMove is - specified (which includes the previous flag), this is even the default - operation + If wxDrag_AllowMove is included in the flags, data may + be moved and not only copied (default). If wxDrag_DefaultMove is + specified (which includes the previous flag), this is even the default + operation @returns Returns the operation requested by the user, may be wxDragCopy, - wxDragMove, wxDragLink, wxDragCancel or wxDragNone if - an error occurred. + wxDragMove, wxDragLink, wxDragCancel or wxDragNone if + an error occurred. */ virtual wxDragResult DoDragDrop(int flags = wxDrag_CopyOnly); /** Returns the wxDataObject object that has been assigned previously. */ - wxDataObject * GetDataObject(); + wxDataObject* GetDataObject(); /** Overridable: you may give some custom UI feedback during the drag and drop @@ -264,15 +250,14 @@ public: slow. @param effect - The effect to implement. One of wxDragCopy, wxDragMove, wxDragLink and + The effect to implement. One of wxDragCopy, wxDragMove, wxDragLink and wxDragNone. - @param scrolling - @true if the window is scrolling. MSW only. + @true if the window is scrolling. MSW only. @returns Return @false if you want default feedback, or @true if you - implement your own feedback. The return values is - ignored under GTK. + implement your own feedback. The return values is + ignored under GTK. */ virtual bool GiveFeedback(wxDragResult effect); @@ -280,10 +265,9 @@ public: Set the icon to use for a certain drag result. @param res - The drag result to set the icon for. - + The drag result to set the icon for. @param cursor - The ion to show when this drag result occurs. + The ion to show when this drag result occurs. */ void SetCursor(wxDragResult res, const wxCursor& cursor); @@ -306,8 +290,7 @@ public: @category{dnd} @seealso - @ref overview_wxdndoverview "Drag and drop overview", wxDropSource, - wxDropTarget, wxTextDropTarget + @ref overview_wxdndoverview, wxDropSource, wxDropTarget, wxTextDropTarget */ class wxFileDropTarget : public wxDropTarget { @@ -327,13 +310,11 @@ public: Override this function to receive dropped files. @param x - The x coordinate of the mouse. - + The x coordinate of the mouse. @param y - The y coordinate of the mouse. - + The y coordinate of the mouse. @param filenames - An array of filenames. + An array of filenames. */ virtual bool OnDropFiles(wxCoord x, wxCoord y, const wxArrayString& filenames); @@ -348,9 +329,8 @@ public: This macro creates either a cursor (MSW) or an icon (elsewhere) with the given name. Under MSW, the cursor is loaded from the resource file and the icon is loaded from XPM file under other platforms. - This macro should be used with @ref wxDropSource::wxdropsource "wxDropSource constructor". */ -#define wxIconOrCursor wxDROP_ICON(const char * name) /* implementation is private */ +#define wxIconOrCursor wxDROP_ICON(const char* name) /* implementation is private */ diff --git a/interface/docmdi.h b/interface/docmdi.h index 8f253a15bb..b1c5b0931d 100644 --- a/interface/docmdi.h +++ b/interface/docmdi.h @@ -23,7 +23,7 @@ @category{FIXME} @seealso - @ref overview_docviewoverview "Document/view overview", wxMDIParentFrame + @ref overview_docviewoverview, wxMDIParentFrame */ class wxDocMDIParentFrame : public wxMDIParentFrame { @@ -33,7 +33,7 @@ public: Constructor. */ wxDocMDIParentFrame(); - wxDocMDIParentFrame(wxDocManager* manager, wxFrame * parent, + wxDocMDIParentFrame(wxDocManager* manager, wxFrame* parent, wxWindowID id, const wxString& title, const wxPoint& pos = wxDefaultPosition, @@ -50,7 +50,7 @@ public: /** Creates the window. */ - bool Create(wxDocManager* manager, wxFrame * parent, + bool Create(wxDocManager* manager, wxFrame* parent, wxWindowID id, const wxString& title, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, @@ -60,7 +60,6 @@ public: /** Deletes all views and documents. If no user input cancelled the operation, the frame will be destroyed and the application will exit. - Since understanding how document/view clean-up takes place can be difficult, the implementation of this function is shown below. */ @@ -85,7 +84,7 @@ public: @category{FIXME} @seealso - @ref overview_docviewoverview "Document/view overview", wxMDIChildFrame + @ref overview_docviewoverview, wxMDIChildFrame */ class wxDocMDIChildFrame : public wxMDIChildFrame { @@ -132,23 +131,21 @@ public: /** Sets the document for this frame. */ - void SetDocument(wxDocument * doc); + void SetDocument(wxDocument* doc); /** Sets the view for this frame. */ - void SetView(wxView * view); + void SetView(wxView* view); /** wxDocument* m_childDocument - The document associated with the frame. */ /** wxView* m_childView - The view associated with the frame. */ }; diff --git a/interface/docview.h b/interface/docview.h index 2cbade4595..da04a3d79a 100644 --- a/interface/docview.h +++ b/interface/docview.h @@ -26,64 +26,49 @@ public: Constructor. Create instances dynamically near the start of your application after creating a wxDocManager instance, and before doing any document or view operations. - - @e manager is the document manager object which manages this template. - - @e descr is a short description of what the template is for. This string will + @a manager is the document manager object which manages this template. + @a descr is a short description of what the template is for. This string will be displayed in the file filter list of Windows file selectors. - - @e filter is an appropriate file filter such as @c *.txt. - - @e dir is the default directory to use for file selectors. - - @e ext is the default file extension (such as txt). - - @e docTypeName is a name that should be unique for a given type of document, + @a filter is an appropriate file filter such as @c *.txt. + @a dir is the default directory to use for file selectors. + @a ext is the default file extension (such as txt). + @a docTypeName is a name that should be unique for a given type of document, used for gathering a list of views relevant to a particular document. - - @e viewTypeName is a name that should be unique for a given view. - - @e docClassInfo is a pointer to the run-time document class information as + @a viewTypeName is a name that should be unique for a given view. + @a docClassInfo is a pointer to the run-time document class information as returned by the CLASSINFO macro, e.g. CLASSINFO(MyDocumentClass). If this is not supplied, you will need to derive a new wxDocTemplate class and override the CreateDocument member to return a new document instance on demand. - - @e viewClassInfo is a pointer to the run-time view class information as returned + @a viewClassInfo is a pointer to the run-time view class information as returned by the CLASSINFO macro, e.g. CLASSINFO(MyViewClass). If this is not supplied, you will need to derive a new wxDocTemplate class and override the CreateView member to return a new view instance on demand. - - @e flags is a bit list of the following: - + @a flags is a bit list of the following: wxTEMPLATE_VISIBLE The template may be displayed to the user in dialogs. wxTEMPLATE_INVISIBLE The template may not be displayed to the user in dialogs. wxDEFAULT_TEMPLATE_FLAGS Defined as wxTEMPLATE_VISIBLE. - @b Wx::DocTemplate-new( docmgr, descr, filter, dir, ext, docTypeName, viewTypeName, docClassInfo, viewClassInfo, flags ) - will construct document and view objects from the class information @b Wx::DocTemplate-new( docmgr, descr, filter, dir, ext, docTypeName, viewTypeName, docClassName, viewClassName, flags ) - will construct document and view objects from perl packages @b Wx::DocTemplate-new( docmgr, descr, filter, dir, ext, docTypeName, viewTypeName ) - @c Wx::DocTemplate::CreateDocument() and @c Wx::DocTemplate::CreateView() must be overridden */ @@ -93,8 +78,8 @@ public: const wxString& ext, const wxString& docTypeName, const wxString& viewTypeName, - wxClassInfo* docClassInfo = @NULL, - wxClassInfo* viewClassInfo = @NULL, + wxClassInfo* docClassInfo = NULL, + wxClassInfo* viewClassInfo = NULL, long flags = wxDEFAULT_TEMPLATE_FLAGS); /** @@ -108,11 +93,10 @@ public: a wxClassInfo parameter to the template constructor, you will need to override this function to return an appropriate document instance. - This function calls InitDocument() which in turns calls wxDocument::OnCreate. */ - wxDocument * CreateDocument(const wxString& path, long flags = 0); + wxDocument* CreateDocument(const wxString& path, long flags = 0); /** Creates a new instance of the associated view class. If you have not supplied @@ -120,7 +104,7 @@ public: this function to return an appropriate view instance. */ - wxView * CreateView(wxDocument * doc, long flags = 0); + wxView* CreateView(wxDocument* doc, long flags = 0); /** Returns the default file extension for the document data, as passed to the @@ -143,7 +127,7 @@ public: Returns a pointer to the document manager instance for which this template was created. */ - wxDocManager * GetDocumentManager(); + wxDocManager* GetDocumentManager(); /** Returns the document type name, as passed to the document template constructor. @@ -198,7 +182,7 @@ public: created. Should not be called by the application. */ - void SetDocumentManager(wxDocManager * manager); + void SetDocumentManager(wxDocManager* manager); /** Sets the file filter. @@ -213,28 +197,24 @@ public: /** wxString m_defaultExt - The default extension for files of this type. */ /** wxString m_description - A short description of this template. */ /** wxString m_directory - The default directory for files of this type. */ /** wxClassInfo* m_docClassInfo - Run-time class information that allows document instances to be constructed dynamically. */ @@ -242,35 +222,30 @@ public: /** wxString m_docTypeName - The named type of the document associated with this template. */ /** wxDocTemplate* m_documentManager - A pointer to the document manager for which this template was created. */ /** wxString m_fileFilter - The file filter (such as @c *.txt) to be used in file selector dialogs. */ /** long m_flags - The flags passed to the constructor. */ /** wxClassInfo* m_viewClassInfo - Run-time class information that allows view instances to be constructed dynamically. */ @@ -278,7 +253,6 @@ public: /** wxString m_viewTypeName - The named type of the view associated with this template. */ }; @@ -307,10 +281,8 @@ public: Constructor. Create a document manager instance dynamically near the start of your application before doing any document or view operations. - - @e flags is currently unused. - - If @e initialize is @true, the Initialize() function will be called + @a flags is currently unused. + If @a initialize is @true, the Initialize() function will be called to create a default history list object. If you derive from wxDocManager, you may wish to call the base constructor with @false, and then call Initialize in your own constructor, @@ -318,7 +290,7 @@ public: your own Initialize or OnCreateFileHistory functions to be called. */ wxDocManager(long flags = wxDEFAULT_DOCMAN_FLAGS, - bool initialize = @true); + bool initialize = true); /** Destructor. @@ -328,12 +300,12 @@ public: /** Sets the current view. */ - void ActivateView(wxView* doc, bool activate = @true); + void ActivateView(wxView* doc, bool activate = true); /** Adds the document to the list of documents. */ - void AddDocument(wxDocument * doc); + void AddDocument(wxDocument* doc); /** Adds a file to the file history list, if we have a pointer to an appropriate @@ -344,20 +316,18 @@ public: /** Adds the template to the document manager's template list. */ - void AssociateTemplate(wxDocTemplate * temp); + void AssociateTemplate(wxDocTemplate* temp); /** Closes all currently opened documents. */ - bool CloseDocuments(bool force = @true); + bool CloseDocuments(bool force = true); /** - Creates a new document in a manner determined by the @e flags parameter, which + Creates a new document in a manner determined by the @a flags parameter, which can be: - wxDOC_NEW Creates a fresh document. wxDOC_SILENT Silently loads the given document file. - If wxDOC_NEW is present, a new document will be created and returned, possibly after asking the user for a template to use if there is more than one document @@ -368,7 +338,6 @@ public: a file selector for the file to load, and the template to use will be determined by the extension (Windows) or by popping up a template choice list (other platforms). - If the maximum number of documents has been reached, this function will delete the oldest currently loaded document before creating a new one. */ @@ -386,7 +355,7 @@ public: /** Removes the template from the list of templates. */ - void DisassociateTemplate(wxDocTemplate * temp); + void DisassociateTemplate(wxDocTemplate* temp); //@{ /** @@ -399,7 +368,7 @@ public: /** Loads the file history from a config object. - @sa wxConfig + @see wxConfig */ void FileHistoryLoad(wxConfigBase& config); @@ -413,7 +382,7 @@ public: Saves the file history into a config object. This must be called explicitly by the application. - @sa wxConfig + @see wxConfig */ void FileHistorySave(wxConfigBase& resourceFile); @@ -421,7 +390,6 @@ public: Use this menu for appending recently-visited document filenames, for convenient access. Calling this function with a valid menu pointer enables the history list functionality. - Note that you can add multiple menus using this function, to be managed by the file history object. */ @@ -431,17 +399,17 @@ public: Given a path, try to find template that matches the extension. This is only an approximate method of finding a template for creating a document. */ - wxDocTemplate * FindTemplateForPath(const wxString& path); + wxDocTemplate* FindTemplateForPath(const wxString& path); /** Returns the document associated with the currently active view (if any). */ - wxDocument * GetCurrentDocument(); + wxDocument* GetCurrentDocument(); /** Returns the currently active view */ - wxView * GetCurrentView(); + wxView* GetCurrentView(); /** Returns a reference to the list of documents. @@ -451,7 +419,7 @@ public: /** Returns a pointer to file history. */ - wxFileHistory * GetFileHistory(); + wxFileHistory* GetFileHistory(); /** Returns the number of files currently stored in the file history. @@ -484,7 +452,6 @@ public: vetoed by passing @false to the second argument, allowing the derived class's constructor to call Initialize, possibly calling a different OnCreateFileHistory from the default. - The bottom line: if you're not deriving from Initialize, forget it and construct wxDocManager with no arguments. */ @@ -503,7 +470,7 @@ public: Called from Initialize(). */ - wxFileHistory * OnCreateFileHistory(); + wxFileHistory* OnCreateFileHistory(); /** Closes and deletes the currently active document. @@ -544,26 +511,23 @@ public: /** Removes the document from the list of documents. */ - void RemoveDocument(wxDocument * doc); + void RemoveDocument(wxDocument* doc); /** Under Windows, pops up a file selector with a list of filters corresponding to document templates. The wxDocTemplate corresponding to the selected file's extension is returned. - On other platforms, if there is more than one document template a choice list is popped up, followed by a file selector. - This function is used in CreateDocument(). - (doctemplate, path) = My::DocManager-SelectDocumentPath( ... ); */ - wxDocTemplate * SelectDocumentPath(wxDocTemplate ** templates, - int noTemplates, - wxString& path, - long flags, - bool save); + wxDocTemplate* SelectDocumentPath(wxDocTemplate** templates, + int noTemplates, + wxString& path, + long flags, + bool save); /** Returns a document template by asking the user (if there is more than one @@ -571,20 +535,19 @@ public: This function is used in CreateDocument(). @param templates - Pointer to an array of templates from which to choose a desired template. - + Pointer to an array of templates from which to choose a desired template. @param noTemplates - Number of templates being pointed to by the templates pointer. - + Number of templates being pointed to by the templates pointer. @param sort - If more than one template is passed in in templates, - then this parameter indicates whether the list of templates that the user - will have to choose from is sorted or not when shown the choice box dialog. - Default is @false. + If more than one template is passed in in templates, + then this parameter indicates whether the list of templates that the user + will have to choose from is sorted or not when shown the choice box dialog. + + Default is @false. */ - wxDocTemplate * SelectDocumentType(wxDocTemplate ** templates, - int noTemplates, - bool sort=@false); + wxDocTemplate* SelectDocumentType(wxDocTemplate** templates, + int noTemplates, + bool sort = false); /** Returns a document template by asking the user (if there is more than one @@ -595,20 +558,19 @@ public: such. @param templates - Pointer to an array of templates from which to choose a desired template. - + Pointer to an array of templates from which to choose a desired template. @param noTemplates - Number of templates being pointed to by the templates pointer. - + Number of templates being pointed to by the templates pointer. @param sort - If more than one template is passed in in templates, - then this parameter indicates whether the list of templates that the user - will have to choose from is sorted or not when shown the choice box dialog. - Default is @false. + If more than one template is passed in in templates, + then this parameter indicates whether the list of templates that the user + will have to choose from is sorted or not when shown the choice box dialog. + + Default is @false. */ - wxDocTemplate * SelectViewType(wxDocTemplate ** templates, - int noTemplates, - bool sort=@false); + wxDocTemplate* SelectViewType(wxDocTemplate** templates, + int noTemplates, + bool sort = false); /** Sets the directory to be displayed to the user when opening a file. Initially @@ -628,28 +590,24 @@ public: /** wxView* m_currentView - The currently active view. */ /** int m_defaultDocumentNameCounter - Stores the integer to be used for the next default document name. */ /** wxList m_docs - A list of all documents. */ /** wxFileHistory* m_fileHistory - A pointer to an instance of wxFileHistory, which manages the history of recently-visited files on the File menu. */ @@ -657,21 +615,18 @@ public: /** long m_flags - Stores the flags passed to the constructor. */ /** The directory last selected by the user when opening a file. - wxFileHistory* m_fileHistory */ /** int m_maxDocsOpen - Stores the maximum number of documents that can be opened before existing documents are closed. By default, this is 10,000. */ @@ -717,20 +672,18 @@ public: need to call this function from any place where you know the view must be active, and the framework will need to get the current view. - The prepackaged view frame wxDocChildFrame calls Activate() from its OnActivate member. - This function calls OnActivateView(). */ virtual void Activate(bool activate); /** - Closes the view by calling OnClose. If @e deleteWindow is @true, this function + Closes the view by calling OnClose. If @a deleteWindow is @true, this function should delete the window associated with the view. */ - virtual bool Close(bool deleteWindow = @true); + virtual bool Close(bool deleteWindow = true); /** Gets a pointer to the document associated with the view. @@ -748,7 +701,7 @@ public: pages instead of the frames and this is why this method returns a wxWindow and not a wxFrame. */ - wxWindow * GetFrame(); + wxWindow* GetFrame(); /** Gets the name associated with the view (passed to the wxDocTemplate @@ -762,8 +715,8 @@ public: implementation does nothing. */ - virtual void OnActivateView(bool activate, wxView * activeView, - wxView * deactiveView); + virtual void OnActivateView(bool activate, wxView* activeView, + wxView* deactiveView); /** Called when the filename has changed. The default implementation constructs a @@ -777,7 +730,7 @@ public: may wish to do some cleaning up operations in this function, @e if a call to wxDocument::Close succeeded. For example, if your views all share the same window, you need to disassociate the window from the view - and perhaps clear the window. If @e deleteWindow is @true, delete the + and perhaps clear the window. If @a deleteWindow is @true, delete the frame associated with the view. */ virtual bool OnClose(bool deleteWindow); @@ -795,7 +748,6 @@ public: wxDocChildFrame or a derived class. This wxDocChildFrame provides user interface elements to view and/or edit the contents of the wxDocument. - By default, simply returns @true. If the function returns @false, the view will be deleted. */ @@ -805,10 +757,8 @@ public: If the printing framework is enabled in the library, this function returns a wxPrintout object for the purposes of printing. It should create a new object every time it is called; the framework will delete objects it creates. - By default, this function returns an instance of wxDocPrintout, which prints and previews one page by calling OnDraw(). - Override to return an instance of a class other than wxDocPrintout. */ virtual wxPrintout* OnCreatePrintout(); @@ -819,10 +769,10 @@ public: virtual void OnDraw(wxDC* dc); /** - Called when the view should be updated. @e sender is a pointer to the view + Called when the view should be updated. @a sender is a pointer to the view that sent the update request, or @NULL if no single view requested the update (for instance, - when the document is opened). @e hint is as yet unused but may in future contain + when the document is opened). @a hint is as yet unused but may in future contain application-specific information for making updating more efficient. */ virtual void OnUpdate(wxView* sender, wxObject* hint); @@ -836,7 +786,6 @@ public: /** Sets the frame associated with this view. The application should call this if possible, to tell the view about the frame. - See GetFrame() for the explanation about the mismatch between the "Frame'' in the method name and the type of its parameter. */ @@ -849,7 +798,6 @@ public: /** wxDocument* m_viewDocument - The document associated with this view. There may be more than one view per document, but there can never be more than one document for one view. */ @@ -857,14 +805,12 @@ public: /** wxFrame* m_viewFrame - Frame associated with the view, if any. */ /** wxString m_viewTypeName - The view type name given to the wxDocTemplate constructor, copied to this variable when the view is created. Not currently used by the framework. */ @@ -888,7 +834,7 @@ public: @category{dvf} @seealso - @ref overview_docviewoverview "Document/view overview", wxFrame + @ref overview_docviewoverview, wxFrame */ class wxDocChildFrame : public wxFrame { @@ -934,23 +880,21 @@ public: /** Sets the document for this frame. */ - void SetDocument(wxDocument * doc); + void SetDocument(wxDocument* doc); /** Sets the view for this frame. */ - void SetView(wxView * view); + void SetView(wxView* view); /** wxDocument* m_childDocument - The document associated with the frame. */ /** wxView* m_childView - The view associated with the frame. */ }; @@ -973,7 +917,7 @@ public: @category{dvf} @seealso - @ref overview_docviewoverview "Document/view overview", wxFrame + @ref overview_docviewoverview, wxFrame */ class wxDocParentFrame : public wxFrame { @@ -983,7 +927,7 @@ public: Constructor. */ wxDocParentFrame(); - wxDocParentFrame(wxDocManager* manager, wxFrame * parent, + wxDocParentFrame(wxDocManager* manager, wxFrame* parent, wxWindowID id, const wxString& title, const wxPoint& pos = wxDefaultPosition, @@ -1000,7 +944,7 @@ public: /** Used in two-step construction. */ - bool Create(wxDocManager* manager, wxFrame * parent, + bool Create(wxDocManager* manager, wxFrame* parent, wxWindowID id, const wxString& title, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, @@ -1010,12 +954,11 @@ public: /** Returns the associated @ref overview_wxdocmanager "document manager object". */ - wxDocManager * GetDocumentManager(); + wxDocManager* GetDocumentManager(); /** Deletes all views and documents. If no user input cancelled the operation, the frame will be destroyed and the application will exit. - Since understanding how document/view clean-up takes place can be difficult, the implementation of this function is shown below. */ @@ -1058,7 +1001,7 @@ public: If the view is not already in the list of views, adds the view and calls OnChangedViewList. */ - virtual bool AddView(wxView * view); + virtual bool AddView(wxView* view); /** Closes the document, by calling OnSaveModified and then (if this returned @true) @@ -1079,7 +1022,6 @@ public: /** Returns a pointer to the command processor associated with this document. - See wxCommandProcessor. */ wxCommandProcessor* GetCommandProcessor(); @@ -1115,10 +1057,9 @@ public: /** A convenience function to get the first view for a document, because in many cases a document will only have a single view. - See also: GetViews() */ - wxView * GetFirstView(); + wxView* GetFirstView(); /** Gets the title for this document. The document title is used for an associated @@ -1136,7 +1077,6 @@ public: /** Returns the list whose elements are the views on the document. - See also: GetFirstView() */ wxList GetViews(); @@ -1147,7 +1087,6 @@ public: You may need to override this if your document view maintains its own record of being modified (for example if using wxTextWindow to view and edit the document). - See also Modify(). */ virtual bool IsModified(); @@ -1157,7 +1096,6 @@ public: Override this function and call it from your own LoadObject before streaming your own data. LoadObject is called by the framework automatically when the document contents need to be loaded. - Note that only one of these forms exists, depending on how wxWidgets was configured. */ @@ -1171,7 +1109,6 @@ public: You may need to override this if your document view maintains its own record of being modified (for example if using wxTextWindow to view and edit the document). - See also IsModified(). */ virtual void Modify(bool modify); @@ -1202,7 +1139,6 @@ public: Override this function if you want a different (or no) command processor to be created when the document is created. By default, it returns an instance of wxCommandProcessor. - See wxCommandProcessor. */ virtual wxCommandProcessor* OnCreateCommandProcessor(); @@ -1262,7 +1198,6 @@ public: Override this function and call it from your own SaveObject before streaming your own data. SaveObject is called by the framework automatically when the document contents need to be saved. - Note that only one of these forms exists, depending on how wxWidgets was configured. */ @@ -1276,10 +1211,9 @@ public: for its deletion. Normally you should not call this; override OnCreateCommandProcessor instead. - See wxCommandProcessor. */ - virtual void SetCommandProcessor(wxCommandProcessor * processor); + virtual void SetCommandProcessor(wxCommandProcessor* processor); /** Sets the document type name for this document. See the comment for @@ -1296,11 +1230,10 @@ public: /** Sets the filename for this document. Usually called by the framework. - - If @e notifyViews is @true, wxView::OnChangeFilename is called for all views. + If @a notifyViews is @true, wxView::OnChangeFilename is called for all views. */ void SetFilename(const wxString& filename, - bool notifyViews = @false); + bool notifyViews = false); /** Sets the title for this document. The document title is used for an associated @@ -1310,43 +1243,37 @@ public: void SetTitle(const wxString& title); /** - Updates all views. If @e sender is non-@NULL, does not update this view. - - @e hint represents optional information to allow a view to optimize its update. + Updates all views. If @a sender is non-@NULL, does not update this view. + @a hint represents optional information to allow a view to optimize its update. */ - void UpdateAllViews(wxView* sender = @NULL, wxObject* hint = @NULL); + void UpdateAllViews(wxView* sender = NULL, wxObject* hint = NULL); /** wxCommandProcessor* m_commandProcessor - A pointer to the command processor associated with this document. */ /** wxString m_documentFile - Filename associated with this document ("" if none). */ /** bool m_documentModified - @true if the document has been modified, @false otherwise. */ /** wxDocTemplate * m_documentTemplate - A pointer to the template from which this document was created. */ /** wxString m_documentTitle - Document title. The document title is used for an associated frame (if any), and is usually constructed by the framework from the filename. @@ -1355,7 +1282,6 @@ public: /** wxString m_documentTypeName - The document type name given to the wxDocTemplate constructor, copied to this variable when the document is created. If several document templates are created that use the same document type, this variable is used in @@ -1367,7 +1293,6 @@ public: /** wxList m_documentViews - List of wxView instances associated with this document. */ }; @@ -1398,8 +1323,7 @@ public: /** Constructor. Pass the maximum number of files that should be stored and displayed. - - @e idBase defaults to wxID_FILE1 and represents the id given to the first + @a idBase defaults to wxID_FILE1 and represents the id given to the first history menu item. Since menu items can't share the same ID you should change idBase (To one of your own defined IDs) when using more than one wxFileHistory in your application. @@ -1449,7 +1373,7 @@ public: /** Returns the list of menus that are managed by this file history object. - @sa UseMenu() + @see UseMenu() */ const wxList GetMenus(); @@ -1457,7 +1381,7 @@ public: Loads the file history from the given config object. This function should be called explicitly by the application. - @sa wxConfig + @see wxConfig */ void Load(wxConfigBase& config); @@ -1475,7 +1399,7 @@ public: Saves the file history into the given config object. This must be called explicitly by the application. - @sa wxConfig + @see wxConfig */ void Save(wxConfigBase& config); @@ -1495,7 +1419,6 @@ public: /** char** m_fileHistory - A character array of strings corresponding to the most recently opened files. */ @@ -1503,21 +1426,18 @@ public: /** size_t m_fileHistoryN - The number of files stored in the history array. */ /** size_t m_fileMaxFiles - The maximum number of files to be stored and displayed on the menu. */ /** wxMenu* m_fileMenu - The file menu used to display the file history list (if enabled). */ }; diff --git a/interface/dragimag.h b/interface/dragimag.h index 94d2bdee84..56cc004960 100644 --- a/interface/dragimag.h +++ b/interface/dragimag.h @@ -50,33 +50,26 @@ public: //@{ /** ) - Constructs a drag image an optional cursor. This constructor is only available for wxGenericDragImage, and can be used when the application supplies DoDrawImage() and GetImageRect(). @param image - Icon or bitmap to be used as the drag image. The bitmap can - have a mask. - + Icon or bitmap to be used as the drag image. The bitmap can + have a mask. @param text - Text used to construct a drag image. - + Text used to construct a drag image. @param cursor - Optional cursor to combine with the image. - + Optional cursor to combine with the image. @param hotspot - This parameter is deprecated. - + This parameter is deprecated. @param treeCtrl - Tree control for constructing a tree drag image. - + Tree control for constructing a tree drag image. @param listCtrl - List control for constructing a list drag image. - + List control for constructing a list drag image. @param id - Tree or list control item id. + Tree or list control item id. */ wxDragImage(); wxDragImage(const wxBitmap& image, @@ -96,43 +89,36 @@ public: second to specify the bounding area. This form is equivalent to using the first form, but more convenient than working out the bounding rectangle explicitly. - You need to then call Show() and Move() to show the image on the screen. - Call EndDrag() when the drag has finished. - Note that this call automatically calls CaptureMouse. @param hotspot - The location of the drag position relative to the upper-left corner - of the image. - + The location of the drag position relative to the upper-left corner + of the image. @param window - The window that captures the mouse, and within which the dragging - is limited unless fullScreen is @true. - + The window that captures the mouse, and within which the dragging + is limited unless fullScreen is @true. @param boundingWindow - In the second form of the function, specifies the - area within which the drag occurs. - + In the second form of the function, specifies the + area within which the drag occurs. @param fullScreen - If @true, specifies that the drag will be visible over the full - screen, or over as much of the screen as is specified by rect. Note that the - mouse will - still be captured in window. - + If @true, specifies that the drag will be visible over the full + screen, or over as much of the screen as is specified by rect. Note that + the mouse will + still be captured in window. @param rect - If non-@NULL, specifies the rectangle (in screen coordinates) that - bounds the dragging operation. Specifying this can make the operation more + If non-@NULL, specifies the rectangle (in screen coordinates) that + bounds the dragging operation. Specifying this can make the operation more efficient - by cutting down on the area under consideration, and it can also make a visual - difference - since the drag is clipped to this area. + by cutting down on the area under consideration, and it can also make a + visual difference + since the drag is clipped to this area. */ bool BeginDrag(const wxPoint& hotspot, wxWindow* window, - bool fullScreen = @false, - wxRect* rect = @NULL); + bool fullScreen = false, + wxRect* rect = NULL); bool BeginDrag(const wxPoint& hotspot, wxWindow* window, wxWindow* boundingWindow); //@} @@ -140,7 +126,6 @@ public: /** Draws the image on the device context with top-left corner at the given position. - This function is only available with wxGenericDragImage, to allow applications to draw their own image instead of using an actual bitmap. If you override this @@ -151,7 +136,6 @@ public: /** Call this when the drag has finished. - Note that this call automatically calls ReleaseMouse. */ bool EndDrag(); @@ -160,7 +144,6 @@ public: Returns the rectangle enclosing the image, assuming that the image is drawn with its top-left corner at the given point. - This function is available in wxGenericDragImage only, and may be overridden (together with wxDragImage::DoDrawImage) to provide a virtual drawing capability. @@ -178,10 +161,8 @@ public: Call this to move the image to a new position. The image will only be shown if Show() has been called previously (for example at the start of the drag). - - @e pt is the position in client coordinates (relative to the window specified + @a pt is the position in client coordinates (relative to the window specified in BeginDrag). - You can move the image either when the image is hidden or shown, but in general dragging will be smoother if you move the image when it is shown. @@ -203,13 +184,11 @@ public: graphic @e minus the objects to be dragged, and leave the window itself to be updated by the drag image. This can provide eerily smooth, flicker-free drag behaviour. - The default implementation copies the window contents to the backing bitmap. A new implementation will normally copy information from another source, such as from its own backing bitmap if it has one, or directly from internal data structures. - This function is available in wxGenericDragImage only. */ bool UpdateBackingFromWindow(wxDC& windowDC, wxMemoryDC& destDC, diff --git a/interface/dynarray.h b/interface/dynarray.h index 706af3792f..3f58b6a209 100644 --- a/interface/dynarray.h +++ b/interface/dynarray.h @@ -150,19 +150,17 @@ @category{FIXME} @seealso - @ref overview_wxcontaineroverview "Container classes overview", wxListT, - wxVectorT + @ref overview_wxcontaineroverview, wxListT, wxVectorT */ class wxArray { public: //@{ /** - Appends the given number of @e copies of the @e item to the array + Appends the given number of @a copies of the @a item to the array consisting of the elements of type @e T. - The first version is used with wxArray. The second is used with wxSortedArray, - returning the index where @e item is stored. The third and the + returning the index where @a item is stored. The third and the fourth ones are used with wxObjArray. There is an important difference between them: if you give a pointer to the array, it will take ownership of it, i.e. will delete it when the item is deleted from the array. If you give a reference @@ -171,25 +169,22 @@ public: because the other array types never take ownership of their elements. Also note that you cannot append more than one pointer as reusing it would lead to deleting it twice (or more) and hence to a crash. - You may also use WX_APPEND_ARRAY macro to append all elements of one array to another one but it is more efficient to use - @e copies parameter and modify the elements in place later if you plan to + @a copies parameter and modify the elements in place later if you plan to append a lot of items. */ void Add(T item, size_t copies = 1); size_t Add(T item); - void Add(T * item); - void Add(T & item, size_t copies = 1); + void Add(T* item); + void Add(T& item, size_t copies = 1); //@} /** - Inserts the given @e item into the array in the specified @e index + Inserts the given @a item into the array in the specified @e index position. - Be aware that you will set out the order of the array if you give a wrong position. - This function is useful in conjunction with wxArray::IndexForInsert for a common operation of "insert only if not found". @@ -235,7 +230,6 @@ public: should avoid deleting wxObjArray through a wxBaseArray pointer (as you would never use wxBaseArray anyhow it shouldn't be a problem) and that you should not derive your own classes from the array classes. - @ref wxArray::ctordef "wxArray default constructor" @ref wxArray::ctorcopy "wxArray copy constructors and assignment operators" @@ -247,7 +241,6 @@ public: //@{ /** (T first, T second)@e compareFunction) - There is no default constructor for wxSortedArray classes - you must initialize it with a function to use for item comparison. It is a function which is passed @@ -265,7 +258,7 @@ public: wxArray::Remove doesn't delete it. The function returns the pointer to the removed element. */ - T * Detach(size_t index); + T* Detach(size_t index); /** Empties the array. For wxObjArray classes, this destroys all of the array @@ -284,34 +277,29 @@ public: /** The first version of the function is for wxArray and wxObjArray, the second is for wxSortedArray only. - Searches the element in the array, starting from either beginning or the end - depending on the value of @e searchFromEnd parameter. @c wxNOT_FOUND is + depending on the value of @a searchFromEnd parameter. @c wxNOT_FOUND is returned if the element is not found, otherwise the index of the element is returned. - 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 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 in the array. */ - int Index(T& item, bool searchFromEnd = @false); + int Index(T& item, bool searchFromEnd = false); int Index(T& item); //@} /** - Search for a place to insert @e item into the sorted array (binary search). + Search for a place to insert @a item into the sorted array (binary search). The index returned is just before the first existing item that is greater or equal (according to the compare function) to the given @e item. - - You have to do extra work to know if the @e item already exists in array. - + You have to do extra work to know if the @a item already exists in array. This function is useful in conjunction with wxArray::AddAt for a common operation of "insert only if not found". @@ -320,19 +308,17 @@ public: //@{ /** - Insert the given number of @e copies of the @e item into the array before - the existing item @e n - thus, @e Insert(something, 0u) will insert an + Insert the given number of @a copies of the @a item into the array before + the existing item @a n - thus, @e Insert(something, 0u) will insert an item in such way that it will become the first array element. - wxSortedArray doesn't have this function because inserting in wrong place would break its sorted condition. - Please see wxArray::Add for explanation of the differences between the overloaded versions of this function. */ void Insert(T item, size_t n, size_t copies = 1); - void Insert(T * item, size_t n); - void Insert(T & item, size_t n, size_t copies = 1); + void Insert(T* item, size_t n); + void Insert(T& item, size_t n, size_t copies = 1); //@} /** @@ -341,10 +327,9 @@ public: bool IsEmpty(); /** - Returns the item at the given position in the array. If @e index is out of + Returns the item at the given position in the array. If @a index is out of bounds, an assert failure is raised in the debug builds but nothing special is done in the release build. - The returned value is of type "reference to the array element type" for all of the array classes. */ @@ -353,7 +338,6 @@ public: /** Returns the last element in the array, i.e. is the same as Item(GetCount() - 1). An assert failure is raised in the debug mode if the array is empty. - The returned value is of type "reference to the array element type" for all of the array classes. */ @@ -365,7 +349,6 @@ public: least) forward declared for WX_DEFINE_ARRAY, WX_DEFINE_SORTED_ARRAY and WX_DECLARE_OBJARRAY macros and must be fully declared before you use WX_DEFINE_OBJARRAY macro. - WX_DEFINE_ARRAY WX_DEFINE_EXPORTED_ARRAY @@ -387,18 +370,17 @@ public: WX_DEFINE_EXPORTED_OBJARRAY WX_DEFINE_USER_EXPORTED_OBJARRAY - To slightly complicate the matters even further, the operator - defined by default for the array iterators by these macros only makes sense if the array element type is not a pointer itself and, although it still works, this provokes warnings from some compilers and to avoid them you should use the @c _PTR versions of the macros above. For example, to define an array of pointers to @c double you should use: + Note that the above macros are generally only useful for wxObject types. There are separate macros for declaring an array of a simple type, such as an int. - The following simple types are supported: int @@ -408,12 +390,9 @@ public: size_t double - To create an array of a simple type, simply append the type you want in CAPS to the array definition. - For example, for an integer array, you'd use one of the following variants: - WX_DEFINE_ARRAY_INT WX_DEFINE_EXPORTED_ARRAY_INT @@ -441,7 +420,6 @@ public: function can also be quite useful if you know in advance how many items you are going to put in the array and will prevent the array code from reallocating the memory more times than needed. - wxArray::Alloc wxArray::Shrink @@ -452,7 +430,6 @@ public: Functions in this section return the total number of array elements and allow to retrieve them - possibly using just the C array indexing [] operator which does exactly the same as wxArray::Item method. - wxArray::GetCount wxArray::IsEmpty @@ -465,24 +442,25 @@ public: /** Removes an element from the array by value: the first item of the - array equal to @e item is removed, an assert failure will result from an + array equal to @a item is removed, an assert failure will result from an attempt to remove an item which doesn't exist in the array. - When an element is removed from wxObjArray it is deleted by the array - use Detach if you don't want this to happen. On the other hand, when an object is removed from a wxArray nothing happens - you should delete it manually if required: + See also WX_CLEAR_ARRAY macro which deletes all elements of a wxArray (supposed to contain pointers). */ Remove(T item); /** - Removes @e count elements starting at @e index from the array. When an + Removes @a count elements starting at @a index from the array. When an element is removed from wxObjArray it is deleted by the array - use Detach if you don't want this to happen. On the other hand, when an object is removed from a wxArray nothing happens - you should delete it manually if required: + See also WX_CLEAR_ARRAY macro which deletes all elements of a wxArray (supposed to contain pointers). */ @@ -512,13 +490,12 @@ public: /** ) - This function ensures that the number of array elements is at least - @e count. If the array has already @e count or more items, nothing is + @e count. If the array has already @a count or more items, nothing is done. Otherwise, @c count - GetCount() elements are added and initialized to the value @e defval. - @sa wxArray::GetCount + @see wxArray::GetCount */ void SetCount(size_t count); @@ -532,19 +509,18 @@ public: /** The notation CMPFUNCT should be read as if we had the following declaration: + where @e T is the type of the array elements. I.e. it is a function returning @e int which is passed two arguments of type @e T *. - Sorts the array using the specified compare function: this function should return a negative, zero or positive value according to whether the first element passed to it is less than, equal to or greater than the second one. - wxSortedArray doesn't have this function because it is always sorted. */ void Sort(CMPFUNC compareFunction); /** - This macro may be used to append all elements of the @e other array to the + This macro may be used to append all elements of the @a other array to the @e array. The two arrays must be of the same type. */ #define void WX_APPEND_ARRAY(wxArray& array, wxArray& other) /* implementation is private */ @@ -558,40 +534,40 @@ public: //@{ /** - This macro declares a new object array class named @e name and containing + This macro declares a new object array class named @a name and containing the elements of type @e T. The second form is used when compiling wxWidgets as a DLL under Windows and array needs to be visible outside the DLL. The third is needed for exporting an array from a user DLL. - Example: + You must use WX_DEFINE_OBJARRAY macro to define the array class - otherwise you would get link errors. */ - WX_DECLARE_OBJARRAY(T, name); - WX_DECLARE_EXPORTED_OBJARRAY(T, name); - WX_DECLARE_USER_EXPORTED_OBJARRAY(T, name); + WX_DECLARE_OBJARRAY(T, name); + WX_DECLARE_EXPORTED_OBJARRAY(T, name); + WX_DECLARE_USER_EXPORTED_OBJARRAY(T, name); //@} //@{ /** - This macro defines a new array class named @e name and containing the + This macro defines a new array class named @a name and containing the elements of type @e T. The second form is used when compiling wxWidgets as a DLL under Windows and array needs to be visible outside the DLL. The third is needed for exporting an array from a user DLL. - Example: + Note that wxWidgets predefines the following standard array classes: @b wxArrayInt, @b wxArrayLong, @b wxArrayShort, @b wxArrayDouble, @b wxArrayPtrVoid. */ - WX_DEFINE_ARRAY(T, name); - WX_DEFINE_EXPORTED_ARRAY(T, name); - WX_DEFINE_USER_EXPORTED_ARRAY(T, name, exportspec); + WX_DEFINE_ARRAY(T, name); + WX_DEFINE_EXPORTED_ARRAY(T, name); + WX_DEFINE_USER_EXPORTED_ARRAY(T, name, exportspec); //@} //@{ /** - This macro defines the methods of the array class @e name not defined by the + This macro defines the methods of the array class @a name not defined by the WX_DECLARE_OBJARRAY macro. You must include the file wx/arrimpl.cpp before using this macro and you must have the full declaration of the class of array elements in scope! If you forget to do the @@ -600,7 +576,6 @@ public: objects of the class will not be copied correctly and their real destructor will not be called. The latter two forms are merely aliases of the first to satisfy some people's sense of symmetry when using the exported declarations. - Example of usage: */ WX_DEFINE_OBJARRAY(name); @@ -610,22 +585,22 @@ public: //@{ /** - This macro defines a new sorted array class named @e name and containing + This macro defines a new sorted array class named @a name and containing the elements of type @e T. The second form is used when compiling wxWidgets as a DLL under Windows and array needs to be visible outside the DLL. The third is needed for exporting an array from a user DLL. - Example: + You will have to initialize the objects of this class by passing a comparison function to the array object constructor like this: */ - WX_DEFINE_SORTED_ARRAY(T, name); - WX_DEFINE_SORTED_EXPORTED_ARRAY(T, name); - WX_DEFINE_SORTED_USER_EXPORTED_ARRAY(T, name); + WX_DEFINE_SORTED_ARRAY(T, name); + WX_DEFINE_SORTED_EXPORTED_ARRAY(T, name); + WX_DEFINE_SORTED_USER_EXPORTED_ARRAY(T, name); //@} /** - This macro may be used to prepend all elements of the @e other array to the + This macro may be used to prepend all elements of the @a other array to the @e array. The two arrays must be of the same type. */ #define void WX_PREPEND_ARRAY(wxArray& array, wxArray& other) /* implementation is private */ diff --git a/interface/dynlib.h b/interface/dynlib.h index 8f389f34a1..b85b42ae26 100644 --- a/interface/dynlib.h +++ b/interface/dynlib.h @@ -26,17 +26,16 @@ public: Retrieves the load address and the size of this module. @param addr - the pointer to the location to return load address in, may be - @NULL - + the pointer to the location to return load address in, may be + @NULL @param len - pointer to the location to return the size of this module in - memory in, may be @NULL + pointer to the location to return the size of this module in + memory in, may be @NULL @returns @true if the load address and module size were retrieved, @false - if this information is not available. + if this information is not available. */ - bool GetAddress(void ** addr, size_t len); + bool GetAddress(void** addr, size_t len); /** Returns the base name of this module, e.g. @c kernel32.dll or @@ -131,7 +130,6 @@ public: /** Returns the string containing the usual extension for shared libraries for the given systems (including the leading dot if not empty). - For example, this function will return @c ".dll" under Windows or (usually) @c ".so" under Unix. */ @@ -141,7 +139,6 @@ 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 or OS/2. */ @@ -150,42 +147,38 @@ public: /** This function resolves a symbol in a loaded DLL, such as a variable or function name. - Returned value will be @NULL if the symbol was not found in the DLL or if an error occurred. @param dllHandle - Valid handle previously returned by - LoadLibrary - + Valid handle previously returned by + LoadLibrary @param name - Name of the symbol. + Name of the symbol. */ - void * GetSymbol(wxDllType dllHandle, const wxString& name); + void* GetSymbol(wxDllType dllHandle, const wxString& name); /** - This function loads a shared library into memory, with @e libname being the + This function loads a shared library into memory, with @a libname being the name of the library: it may be either the full name including path and (platform-dependent) extension, just the basename (no path and no extension) or a basename with extension. In the last two cases, the library will be searched in all standard locations. - - Returns a handle to the loaded DLL. Use @e success parameter to test if it + Returns a handle to the loaded DLL. Use @a success parameter to test if it is valid. If the handle is valid, the library must be unloaded later with UnloadLibrary(). @param libname - Name of the shared object to load. - + Name of the shared object to load. @param success - May point to a bool variable which will be set to @true or - @false; may also be @NULL. + May point to a bool variable which will be set to @true or + @false; may also be @NULL. */ - wxDllType LoadLibrary(const wxString & libname, - bool* success = @NULL); + wxDllType LoadLibrary(const wxString& libname, + bool* success = NULL); /** - This function unloads the shared library. The handle @e dllhandle must have + This function unloads the shared library. The handle @a dllhandle must have been returned by LoadLibrary() previously. */ void UnloadLibrary(wxDllType dllhandle); @@ -223,25 +216,18 @@ public: Returns the platform-specific full name for the library called @e name. E.g. it adds a @c ".dll" extension under Windows and @c "lib" prefix and @c ".so", @c ".sl" or maybe @c ".dylib" extension under Unix. - - The possible values for @e cat are: - + The possible values for @a cat are: wxDL_LIBRARY - normal library - - wxDL_MODULE - a loadable module or plugin - - @sa CanonicalizePluginName() + @see CanonicalizePluginName() */ static wxString CanonicalizeName(const wxString& name, wxDynamicLibraryCategory cat = wxDL_LIBRARY); @@ -252,21 +238,15 @@ public: plugins. The only difference is that compiler and version information are added to the name to ensure that the plugin which is going to be loaded will be compatible with the main program. - - The possible values for @e cat are: - + The possible values for @a cat are: wxDL_PLUGIN_GUI - plugin which uses GUI classes (default) - - wxDL_PLUGIN_BASE - plugin which only uses wxBase */ static wxString CanonicalizePluginName(const wxString& name, @@ -286,12 +266,12 @@ public: static wxDllType GetProgramHandle(); /** - Returns pointer to symbol @e name in the library or @NULL if the library + Returns pointer to symbol @a name in the library or @NULL if the library contains no such symbol. - @sa wxDYNLIB_FUNCTION + @see wxDYNLIB_FUNCTION */ - void * GetSymbol(const wxString& name); + void* GetSymbol(const wxString& name); /** This function is available only under Windows as it is only useful when @@ -302,13 +282,12 @@ public: automatically depending on the current build. Otherwise, this method is identical to GetSymbol(). */ - void * GetSymbolAorW(const wxString& name); + void* GetSymbolAorW(const wxString& name); /** - Returns @true if the symbol with the given @e name is present in the dynamic + Returns @true if the symbol with the given @a name is present in the dynamic library, @false otherwise. Unlike GetSymbol(), this function doesn't log an error message if the symbol is not found. - This function is new since wxWidgets version 2.5.4 */ bool HasSymbol(const wxString& name); @@ -323,45 +302,38 @@ public: of all modules loaded into the address space of the current project, the array elements are object of @c wxDynamicLibraryDetails class. The array will be empty if an error occurred. - This method is currently implemented only under Win32 and Linux and is useful mostly for diagnostics purposes. */ static wxDynamicLibraryDetailsArray ListLoaded(); /** - Loads DLL with the given @e name into memory. The @e flags argument can + Loads DLL with the given @a name into memory. The @a flags argument can be a combination of the following bits: wxDL_LAZY - equivalent of RTLD_LAZY under Unix, ignored elsewhere wxDL_NOW - equivalent of RTLD_NOW under Unix, ignored elsewhere wxDL_GLOBAL - equivalent of RTLD_GLOBAL under Unix, ignored elsewhere wxDL_VERBATIM - don't try to append the appropriate extension to the library name (this is done by default). wxDL_DEFAULT - default flags, same as wxDL_NOW currently wxDL_QUIET - don't log an error message if the library couldn't be loaded. @@ -373,7 +345,6 @@ public: /** Unloads the library from memory. wxDynamicLibrary object automatically calls this method from its destructor if it had been successfully loaded. - The second version is only used if you need to keep the library in memory during a longer period of time than the scope of the wxDynamicLibrary object. In this case you may call Detach() and store @@ -394,22 +365,19 @@ public: @c void * pointer to the correct type and, even more annoyingly, you have to repeat this type twice if you want to declare and define a function pointer all in one line - This macro makes this slightly less painful by allowing you to specify the type only once, as the first parameter, and creating a variable of this type named after the function but with @c pfn prefix and initialized with the - function @e name from the wxDynamicLibrary + function @a name from the wxDynamicLibrary @e dynlib. @param type - the type of the function - + the type of the function @param name - the name of the function to load, not a string (without quotes, - it is quoted automatically by the macro) - + the name of the function to load, not a string (without quotes, + it is quoted automatically by the macro) @param dynlib - the library to load the function from + the library to load the function from */ -#define wxDYNLIB_FUNCTION(type, name, dynlib) /* implementation is private */ +#define wxDYNLIB_FUNCTION(type, name, dynlib) /* implementation is private */ diff --git a/interface/editlbox.h b/interface/editlbox.h index f6061ca124..c6c3bec5d4 100644 --- a/interface/editlbox.h +++ b/interface/editlbox.h @@ -40,28 +40,23 @@ public: Constructor, creating and showing a list box. @param parent - Parent window. Must not be @NULL. - + Parent window. Must not be @NULL. @param id - Window identifier. The value wxID_ANY indicates a default value. - + Window identifier. The value wxID_ANY indicates a default value. @param label - The text shown just before the list control. - + The text shown just before the list control. @param pos - Window position. - + Window position. @param size - Window size. If wxDefaultSize is specified then the window is sized - appropriately. - + Window size. If wxDefaultSize is specified then the window is + sized + appropriately. @param style - Window style. See wxEditableListBox. - + Window style. See wxEditableListBox. @param name - Window name. + Window name. - @sa Create() + @see Create() */ wxEditableListBox(); wxEditableListBox(wxWindow* parent, wxWindowID id, diff --git a/interface/encconv.h b/interface/encconv.h index c9b4c6067b..46ada4c2d1 100644 --- a/interface/encconv.h +++ b/interface/encconv.h @@ -33,9 +33,8 @@ public: wxEncodingConverter(); /** - Return @true if (any text in) multibyte encoding @e encIn can be converted to + 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 on the text to convert in the other). @@ -61,8 +60,7 @@ public: 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 @e enc + 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. */ @@ -71,23 +69,20 @@ public: /** Return equivalents for given font that are used under given platform. Supported platforms: - wxPLATFORM_UNIX wxPLATFORM_WINDOWS wxPLATFORM_OS2 wxPLATFORM_MAC 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). - 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.) @@ -100,8 +95,8 @@ public: 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 @e input_enc encoding and will output string in - @e output_enc encoding. + 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 @@ -109,14 +104,12 @@ public: @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 - try some (lossy) substitutions - e.g. replace unconvertible latin capitals with acute by ordinary capitals, replace en-dash or em-dash by '-' etc. diff --git a/interface/event.h b/interface/event.h index 76774a8f63..0ea3ae466e 100644 --- a/interface/event.h +++ b/interface/event.h @@ -78,7 +78,6 @@ public: /** 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. */ @@ -97,7 +96,6 @@ public: /** 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. */ @@ -108,7 +106,6 @@ public: 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. - 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 @@ -121,14 +118,15 @@ public: happened. See @ref overview_keymodifiers "key modifier constants" 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: + 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 + with this function. */ int GetModifiers(); @@ -138,13 +136,12 @@ public: Obtains the position (in client coordinates) at which the key was pressed. */ wxPoint GetPosition(); - void GetPosition(long * x, long * y); + void GetPosition(long* x, long* y); //@} /** 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. */ @@ -153,7 +150,6 @@ public: /** 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. */ @@ -161,7 +157,6 @@ public: /** 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. */ @@ -170,12 +165,12 @@ public: /** Returns the X position (in client coordinates) of the event. */ -#define long GetX() /* implementation is private */ + long GetX(); /** Returns the Y (in client coordinates) position of the event. */ -#define long GetY() /* implementation is private */ + long GetY(); /** Returns @true if either CTRL or ALT keys was down @@ -189,7 +184,6 @@ public: /** 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. */ @@ -197,7 +191,6 @@ public: /** 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. */ @@ -205,68 +198,54 @@ public: /** 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. */ }; @@ -300,8 +279,8 @@ public: button). @param button - Can be wxJOY_BUTTONn where n is 1, 2, 3 or 4; or wxJOY_BUTTON_ANY to - indicate any button down event. + Can be wxJOY_BUTTONn where n is 1, 2, 3 or 4; or wxJOY_BUTTON_ANY to + indicate any button down event. */ bool ButtonDown(int button = wxJOY_BUTTON_ANY); @@ -309,8 +288,8 @@ 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 - indicate any button down event. + Can be wxJOY_BUTTONn where n is 1, 2, 3 or 4; or wxJOY_BUTTON_ANY to + indicate any button down event. */ bool ButtonIsDown(int button = wxJOY_BUTTON_ANY); @@ -319,8 +298,8 @@ public: button). @param button - Can be wxJOY_BUTTONn where n is 1, 2, 3 or 4; or wxJOY_BUTTON_ANY to - indicate any button down event. + Can be wxJOY_BUTTONn where n is 1, 2, 3 or 4; or wxJOY_BUTTON_ANY to + indicate any button down event. */ bool ButtonUp(int button = wxJOY_BUTTON_ANY); @@ -382,7 +361,7 @@ public: @category{events} @seealso - wxScrollEvent, @ref overview_eventhandlingoverview "Event handling overview" + wxScrollEvent, @ref overview_eventhandlingoverview */ class wxScrollWinEvent : public wxEvent { @@ -420,7 +399,7 @@ public: @category{events} @seealso - @ref overview_eventhandlingoverview "Event handling overview" + @ref overview_eventhandlingoverview */ class wxSysColourChangedEvent : public wxEvent { @@ -446,8 +425,7 @@ public: @category{events} @seealso - @ref overview_eventhandlingoverview "Event handling overview", - wxWindowDestroyEvent + @ref overview_eventhandlingoverview, wxWindowDestroyEvent */ class wxWindowCreateEvent : public wxCommandEvent { @@ -455,7 +433,7 @@ public: /** Constructor. */ - wxWindowCreateEvent(wxWindow* win = @NULL); + wxWindowCreateEvent(wxWindow* win = NULL); }; @@ -474,7 +452,7 @@ public: @category{events} @seealso - @ref overview_eventhandlingoverview "Event handling overview" + @ref overview_eventhandlingoverview */ class wxPaintEvent : public wxEvent { @@ -499,8 +477,8 @@ public: @category{events} @seealso - @ref overview_eventhandlingoverview "Event handling overview", - wxTopLevelWindow::Maximize, wxTopLevelWindow::IsMaximized + @ref overview_eventhandlingoverview, wxTopLevelWindow::Maximize, + wxTopLevelWindow::IsMaximized */ class wxMaximizeEvent : public wxEvent { @@ -523,7 +501,7 @@ public: @category{events} @seealso - @ref overview_eventhandlingoverview "Event handling overview" + @ref overview_eventhandlingoverview */ class wxUpdateUIEvent : public wxCommandEvent { @@ -536,7 +514,6 @@ public: /** Returns @true if it is appropriate to update (send UI update events to) this window. - This function looks at the mode used (see wxUpdateUIEvent::SetMode), the wxWS_EX_PROCESS_UI_UPDATES flag in @e window, the time update events were last sent in idle time, and @@ -547,8 +524,8 @@ public: often as possible. You can reduce the frequency that events are sent by changing the mode and/or setting an update interval. - @sa ResetUpdateTime(), SetUpdateInterval(), - SetMode() + @see ResetUpdateTime(), SetUpdateInterval(), + SetMode() */ static bool CanUpdate(wxWindow* window); @@ -577,7 +554,6 @@ public: will send update events: to all windows, or only to those which specify that they will process the events. - See SetMode(). */ static wxUpdateUIMode GetMode(); @@ -619,7 +595,6 @@ public: /** Returns the current interval between updates in milliseconds. -1 disables updates, 0 updates as frequently as possible. - See SetUpdateInterval(). */ static long GetUpdateInterval(); @@ -630,8 +605,8 @@ public: normally sent in idle time, so this is called at the end of idle processing. - @sa CanUpdate(), SetUpdateInterval(), - SetMode() + @see CanUpdate(), SetUpdateInterval(), + SetMode() */ static void ResetUpdateTime(); @@ -639,8 +614,7 @@ public: Specify how wxWidgets will send update events: to all windows, or only to those which specify that they will process the events. - - @e mode may be one of the following values. + @a mode may be one of the following values. The default is wxUPDATE_UI_PROCESS_ALL. */ static void SetMode(wxUpdateUIMode mode); @@ -654,7 +628,6 @@ public: Sets the interval between updates in milliseconds. Set to -1 to disable updates, or to 0 to update as frequently as possible. The default is 0. - Use this to reduce the overhead of UI update events if your application has a lot of windows. If you set the value to -1 or greater than 0, you may also need to call wxWindow::UpdateWindowUI @@ -703,7 +676,7 @@ public: /** */ - wxClipboardTextEvent(wxEventType commandType = wxEVT_@NULL, + wxClipboardTextEvent(wxEventType commandType = wxEVT_NULL, int id = 0); }; @@ -836,36 +809,30 @@ public: /** Returns @true if the identified mouse button is changing state. Valid - values of @e button are: + values of @a button are: @c wxMOUSE_BTN_LEFT - check if left button was pressed @c wxMOUSE_BTN_MIDDLE - check if middle button was pressed @c wxMOUSE_BTN_RIGHT - check if right button was pressed @c wxMOUSE_BTN_AUX1 - check if the first extra button was pressed @c wxMOUSE_BTN_AUX2 - check if the second extra button was pressed @c wxMOUSE_BTN_ANY - check if any button was pressed */ bool Button(int button); @@ -898,7 +865,7 @@ public: Same as MetaDown() under Mac, same as ControlDown() elsewhere. - @sa wxKeyEvent::CmdDown + @see wxKeyEvent::CmdDown */ bool CmdDown(); @@ -910,13 +877,12 @@ public: /** Returns @true if this was a dragging event (motion while a button is depressed). - @sa Moving() + @see Moving() */ bool Dragging(); /** Returns @true if the mouse was entering the window. - See also Leaving(). */ bool Entering(); @@ -933,11 +899,9 @@ public: /** Returns the number of mouse clicks for this event: 1 for a simple click, 2 for a double-click, 3 for a triple-click and so on. - Currently this function is implemented only in wxMac and returns -1 for the other platforms (you can still distinguish simple clicks from double-clicks as they generate different kinds of events however). - This function is new since wxWidgets version 2.9.0 */ int GetClickCount(); @@ -958,9 +922,7 @@ public: //@{ /** Sets *x and *y to the position at which the event occurred. - Returns the physical mouse position in pixels. - Note that if the mouse event has been artificially generated from a special keyboard combination (e.g. under Windows when the "menu'' key is pressed), the returned position is @c wxDefaultPosition. @@ -990,12 +952,12 @@ public: /** Returns X coordinate of the physical mouse event position. */ -#define long GetX() /* implementation is private */ + long GetX(); /** Returns Y coordinate of the physical mouse event position. */ -#define long GetY() /* implementation is private */ + long GetY(); /** Returns @true if the event was a mouse button event (not necessarily a button @@ -1012,7 +974,6 @@ public: /** Returns @true if the mouse was leaving the window. - See also Entering(). */ bool Leaving(); @@ -1030,14 +991,12 @@ public: /** Returns @true if the left mouse button is currently down, independent of the current event type. - Please notice that it is not the same as LeftDown() which returns @true if the event was generated by the left mouse button being pressed. Rather, it simply describes the state of the left mouse button at the time when the event was generated (so while it will be @true for a left click event, it can also be @true for a right click if it happened while the left mouse button was pressed). - This event is usually used in the mouse event handlers which process "move mouse" messages to determine whether the user is (still) dragging the mouse. */ @@ -1109,28 +1068,24 @@ public: /** bool m_altDown - @true if the Alt key is pressed down. */ /** bool m_controlDown - @true if control key is pressed down. */ /** bool m_leftDown - @true if the left mouse button is currently pressed down. */ /** int m_linesPerAction - The configured number of lines (or whatever) to be scrolled per wheel action. */ @@ -1138,56 +1093,48 @@ public: /** bool m_metaDown - @true if the Meta key is pressed down. */ /** bool m_middleDown - @true if the middle mouse button is currently pressed down. */ /** bool m_rightDown - @true if the right mouse button is currently pressed down. */ /** bool m_shiftDown - @true if shift is pressed down. */ /** int m_wheelDelta - The wheel delta, normally 120. */ /** int m_wheelRotation - The distance the mouse wheel is rotated. */ /** long m_x - X-coordinate of the event. */ /** long m_y - Y-coordinate of the event. */ }; @@ -1210,7 +1157,7 @@ public: @category{events} @seealso - @ref overview_eventhandlingoverview "Event handling overview" + @ref overview_eventhandlingoverview */ class wxDropFilesEvent : public wxEvent { @@ -1219,7 +1166,7 @@ public: Constructor. */ wxDropFilesEvent(WXTYPE id = 0, int noFiles = 0, - wxString* files = @NULL); + wxString* files = NULL); /** Returns an array of filenames. @@ -1233,28 +1180,24 @@ public: /** Returns the position at which the files were dropped. - Returns an array of filenames. */ wxPoint GetPosition(); /** wxString* m_files - An array of filenames. */ /** int m_noFiles - The number of files dropped. */ /** wxPoint m_pos - The point at which the drop took place. */ }; @@ -1295,7 +1238,7 @@ public: Returns client object pointer for a listbox or choice selection event (not valid for a deselection). */ - wxClientData * GetClientObject(); + wxClientData* GetClientObject(); /** Returns extra information dependant on the event objects type. @@ -1332,7 +1275,6 @@ public: deselection one. For the menu events, this method indicates if the menu item just has become checked or unchecked (and thus only makes sense for checkable menu items). - Notice that this method can not be used with wxCheckListBox currently. */ @@ -1386,7 +1328,7 @@ public: @category{events} @seealso - @ref overview_eventhandlingoverview "Event handling overview", wxApp::IsActive + @ref overview_eventhandlingoverview, wxApp::IsActive */ class wxActivateEvent : public wxEvent { @@ -1394,7 +1336,7 @@ public: /** Constructor. */ - wxActivateEvent(WXTYPE eventType = 0, bool active = @true, + wxActivateEvent(WXTYPE eventType = 0, bool active = true, int id = 0); /** @@ -1428,7 +1370,7 @@ public: @seealso @ref overview_wxcommandevent "Command events", @ref - overview_eventhandlingoverview "Event handling overview" + overview_eventhandlingoverview */ class wxContextMenuEvent : public wxCommandEvent { @@ -1437,7 +1379,7 @@ public: Constructor. */ wxContextMenuEvent(WXTYPE id = 0, int id = 0, - const wxPoint& pos=wxDefaultPosition); + const wxPoint& pos = wxDefaultPosition); /** Returns the position in screen coordinates at which the menu should be shown. @@ -1445,7 +1387,6 @@ public: convert to client coordinates. You can also omit a position from wxWindow::PopupMenu in order to use the current mouse pointer position. - If the event originated from a keyboard event, the value returned from this function will be wxDefaultPosition. */ @@ -1481,7 +1422,7 @@ public: @category{events} @seealso - @ref overview_eventhandlingoverview "Event handling overview" + @ref overview_eventhandlingoverview */ class wxEraseEvent : public wxEvent { @@ -1489,12 +1430,12 @@ public: /** Constructor. */ - wxEraseEvent(int id = 0, wxDC* dc = @NULL); + wxEraseEvent(int id = 0, wxDC* dc = NULL); /** Returns the device context associated with the erase event to draw on. */ -#define wxDC* GetDC() /* implementation is private */ + wxDC* GetDC(); }; @@ -1514,7 +1455,7 @@ public: @category{events} @seealso - @ref overview_eventhandlingoverview "Event handling overview" + @ref overview_eventhandlingoverview */ class wxFocusEvent : public wxEvent { @@ -1528,7 +1469,6 @@ public: Returns the window associated with this event, that is the window which had the focus before for the @c wxEVT_SET_FOCUS event and the window which is going to receive focus for the @c wxEVT_KILL_FOCUS one. - Warning: the window pointer may be @NULL! */ }; @@ -1550,7 +1490,7 @@ public: @category{events} @seealso - @ref overview_eventhandlingoverview "Event handling overview" + @ref overview_eventhandlingoverview */ class wxChildFocusEvent : public wxCommandEvent { @@ -1559,15 +1499,14 @@ public: Constructor. @param win - The direct child which is (or which contains the window which is) receiving the - focus. + The direct child which is (or which contains the window which is) receiving + the focus. */ - wxChildFocusEvent(wxWindow * win = @NULL); + wxChildFocusEvent(wxWindow* win = NULL); /** Returns the direct child which receives the focus, or a (grand-)parent of the control receiving the focus. - To get the actually focused control use wxWindow::FindFocus. */ }; @@ -1592,8 +1531,8 @@ public: @category{events} @seealso - wxMouseCaptureChangedEvent, @ref overview_eventhandlingoverview "Event handling - overview", wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture + wxMouseCaptureChangedEvent, @ref overview_eventhandlingoverview, + wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture */ class wxMouseCaptureLostEvent : public wxEvent { @@ -1628,7 +1567,7 @@ public: /** Constructor (used internally by wxWidgets only). */ - wxNotifyEvent(wxEventType eventType = wxEVT_@NULL, int id = 0); + wxNotifyEvent(wxEventType eventType = wxEVT_NULL, int id = 0); /** This is the opposite of Veto(): it explicitly @@ -1646,7 +1585,6 @@ public: /** Prevents the change announced by this event from happening. - It is in general a good idea to notify the user about the reasons for vetoing the change because otherwise the applications behaviour (which just refuses to do what the user wants) might be quite surprising. @@ -1684,8 +1622,7 @@ public: @category{FIXME} @seealso - wxContextHelp, wxDialog, @ref overview_eventhandlingoverview "Event handling - overview" + wxContextHelp, wxDialog, @ref overview_eventhandlingoverview */ class wxHelpEvent : public wxCommandEvent { @@ -1699,20 +1636,16 @@ public: /** Returns the origin of the help event which is one of the following values: - @b Origin_Unknown - Unrecognized event source. @b Origin_Keyboard - Event generated by @c F1 key press. @b Origin_HelpButton - Event generated by wxContextHelp or using the "?" title bur button under MS Windows. @@ -1721,7 +1654,7 @@ public: differently, e.g. by using wxGetMousePosition for the mouse events. - @sa SetOrigin() + @see SetOrigin() */ wxHelpEvent::Origin GetOrigin(); @@ -1734,7 +1667,7 @@ public: /** Set the help event origin, only used internally by wxWidgets normally. - @sa GetOrigin() + @see GetOrigin() */ void SetOrigin(wxHelpEvent::Origin origin); @@ -1762,7 +1695,7 @@ public: @seealso wxScrollBar, wxSlider, wxSpinButton, , wxScrollWinEvent, @ref - overview_eventhandlingoverview "Event handling overview" + overview_eventhandlingoverview */ class wxScrollEvent : public wxCommandEvent { @@ -1811,8 +1744,7 @@ public: @category{events} @seealso - @ref overview_eventhandlingoverview "Event handling overview", wxUpdateUIEvent, - wxWindow::OnInternalIdle + @ref overview_eventhandlingoverview, wxUpdateUIEvent, wxWindow::OnInternalIdle */ class wxIdleEvent : public wxEvent { @@ -1825,16 +1757,15 @@ public: /** Returns @true if it is appropriate to send idle events to this window. - This function looks at the mode used (see wxIdleEvent::SetMode), - and the wxWS_EX_PROCESS_IDLE style in @e window to determine whether idle + and the wxWS_EX_PROCESS_IDLE style in @a window to determine whether idle events should be sent to this window now. By default this will always return @true because the update mode is initially wxIDLE_PROCESS_ALL. You can change the mode to only send idle events to windows with the wxWS_EX_PROCESS_IDLE extra window style set. - @sa SetMode() + @see SetMode() */ static bool CanSend(wxWindow* window); @@ -1842,7 +1773,6 @@ public: Static function returning a value specifying how wxWidgets will send idle events: to all windows, or only to those which specify that they will process the events. - See SetMode(). */ static wxIdleMode GetMode(); @@ -1851,7 +1781,7 @@ public: Returns @true if the OnIdle function processing this event requested more processing time. - @sa RequestMore() + @see RequestMore() */ bool MoreRequested(); @@ -1866,16 +1796,15 @@ public: calling OnIdle) until a new event is posted to the application by the windowing system. - @sa MoreRequested() + @see MoreRequested() */ - void RequestMore(bool needMore = @true); + void RequestMore(bool needMore = true); /** Static function for specifying how wxWidgets will send idle events: to all windows, or only to those which specify that they will process the events. - - @e mode can be one of the following values. + @a mode can be one of the following values. The default is wxIDLE_PROCESS_ALL. */ static void SetMode(wxIdleMode mode); @@ -1894,7 +1823,7 @@ public: @category{events} @seealso - @ref overview_eventhandlingoverview "Event handling overview" + @ref overview_eventhandlingoverview */ class wxInitDialogEvent : public wxEvent { @@ -1927,8 +1856,7 @@ public: @category{events} @seealso - @ref overview_eventhandlingoverview "Event handling overview", - wxWindowCreateEvent + @ref overview_eventhandlingoverview, wxWindowCreateEvent */ class wxWindowDestroyEvent : public wxCommandEvent { @@ -1936,7 +1864,7 @@ public: /** Constructor. */ - wxWindowDestroyEvent(wxWindow* win = @NULL); + wxWindowDestroyEvent(wxWindow* win = NULL); }; @@ -1998,7 +1926,7 @@ public: void SetCurrentFocus(wxWindow* currentFocus); /** - Sets the direction to forward if @e direction is @true, or backward if @c + Sets the direction to forward if @a direction is @true, or backward if @c @false. */ void SetDirection(bool direction); @@ -2036,8 +1964,8 @@ public: @category{events} @seealso - wxMouseCaptureLostEvent, @ref overview_eventhandlingoverview "Event handling - overview", wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture + wxMouseCaptureLostEvent, @ref overview_eventhandlingoverview, + wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture */ class wxMouseCaptureChangedEvent : public wxEvent { @@ -2046,7 +1974,7 @@ public: Constructor. */ wxMouseCaptureChangedEvent(wxWindowID windowId = 0, - wxWindow* gainedCapture = @NULL); + wxWindow* gainedCapture = NULL); /** Returns the window that gained the capture, or @NULL if it was a non-wxWidgets @@ -2127,11 +2055,10 @@ public: /** Call this from your event handler to veto a system shutdown or to signal to the calling application that a window close did not happen. - You can only veto a shutdown if CanVeto() returns @true. */ - void Veto(bool veto = @true); + void Veto(bool veto = true); }; @@ -2151,7 +2078,7 @@ public: @seealso @ref overview_wxcommandevent "Command events", @ref - overview_eventhandlingoverview "Event handling overview" + overview_eventhandlingoverview */ class wxMenuEvent : public wxEvent { @@ -2159,14 +2086,14 @@ public: /** Constructor. */ - wxMenuEvent(WXTYPE id = 0, int id = 0, wxMenu* menu = @NULL); + wxMenuEvent(WXTYPE id = 0, int id = 0, wxMenu* menu = NULL); /** Returns the menu which is being opened or closed. This method should only be used with the @c OPEN and @c CLOSE events and even for them the returned pointer may be @NULL in some ports. */ - wxMenu * GetMenu(); + wxMenu* GetMenu(); /** Returns the menu identifier associated with the event. This method should be @@ -2177,7 +2104,6 @@ public: /** Returns @true if the menu which is being opened or closed is a popup menu, @false if it is a normal one. - This method should only be used with the @c OPEN and @c CLOSE events. */ bool IsPopup(); @@ -2212,18 +2138,17 @@ public: @category{FIXME} @seealso - @ref overview_eventhandlingoverview "Event handling overview", wxEvtHandler + @ref overview_eventhandlingoverview, wxEvtHandler */ class wxEventBlocker : public wxEvtHandler { public: /** Constructs the blocker for the given window and for the given event type. - If @e type is @c wxEVT_ANY, then all events for that window are + If @a type is @c wxEVT_ANY, then all events for that window are blocked. You can call Block() after creation to add other event types to the list of events to block. - - Note that the @e win window @b must remain alive until the + Note that the @a win window @b must remain alive until the wxEventBlocker object destruction. */ wxEventBlocker(wxWindow* win, wxEventType type = wxEVT_ANY); @@ -2260,7 +2185,7 @@ public: @category{FIXME} @seealso - @ref overview_eventhandlingoverview "Event handling overview" + @ref overview_eventhandlingoverview */ class wxEvtHandler : public wxObject { @@ -2281,14 +2206,14 @@ public: This function posts an event to be processed later. @param event - Event to add to process queue. + Event to add to process queue. @remarks The difference between sending an event (using the ProcessEvent - method) and posting it is that in the first case the - event is processed before the function returns, while - in the second case, the function returns immediately - and the event will be processed sometime later - (usually during the next event loop iteration). + method) and posting it is that in the first case the + event is processed before the function returns, while + in the second case, the function returns immediately + and the event will be processed sometime later (usually + during the next event loop iteration). */ virtual void AddPendingEvent(const wxEvent& event); @@ -2300,41 +2225,36 @@ public: 'dynamic' sample for usage. @param id - The identifier (or first of the identifier range) to be - associated with the event handler function. For the version not taking this - argument, it defaults to wxID_ANY. - + The identifier (or first of the identifier range) to be + associated with the event handler function. For the version not taking this + argument, it defaults to wxID_ANY. @param lastId - The second part of the identifier range to be associated with the event handler - function. - + The second part of the identifier range to be associated with the event + handler function. @param eventType - The event type to be associated with this event handler. - + The event type to be associated with this event handler. @param function - The event handler function. Note that this function should - be explicitly converted to the correct type which can be done using a macro - called wxFooEventHandler for the handler for any wxFooEvent. - + The event handler function. Note that this function should + be explicitly converted to the correct type which can be done using a macro + called wxFooEventHandler for the handler for any wxFooEvent. @param userData - Data to be associated with the event table entry. - + Data to be associated with the event table entry. @param eventSink - Object whose member function should be called. If this is @NULL, - this will be used. + Object whose member function should be called. If this is @NULL, + this will be used. */ void Connect(int id, int lastId, wxEventType eventType, wxObjectEventFunction function, - wxObject* userData = @NULL, - wxEvtHandler* eventSink = @NULL); + wxObject* userData = NULL, + wxEvtHandler* eventSink = NULL); void Connect(int id, wxEventType eventType, wxObjectEventFunction function, - wxObject* userData = @NULL, - wxEvtHandler* eventSink = @NULL); + wxObject* userData = NULL, + wxEvtHandler* eventSink = NULL); void Connect(wxEventType eventType, wxObjectEventFunction function, - wxObject* userData = @NULL, - wxEvtHandler* eventSink = @NULL); + wxObject* userData = NULL, + wxEvtHandler* eventSink = NULL); //@} //@{ @@ -2348,81 +2268,76 @@ public: to disconnect functions connected using the (static) event tables. @param id - The identifier (or first of the identifier range) associated with the event + The identifier (or first of the identifier range) associated with the event handler function. - @param lastId - The second part of the identifier range associated with the event handler + The second part of the identifier range associated with the event handler function. - @param eventType - The event type associated with this event handler. - + The event type associated with this event handler. @param function - The event handler function. - + The event handler function. @param userData - Data associated with the event table entry. - + Data associated with the event table entry. @param eventSink - Object whose member function should be called. + Object whose member function should be called. */ - bool Disconnect(wxEventType eventType = wxEVT_@NULL, - wxObjectEventFunction function = @NULL, - wxObject* userData = @NULL, - wxEvtHandler* eventSink = @NULL); + bool Disconnect(wxEventType eventType = wxEVT_NULL, + wxObjectEventFunction function = NULL, + wxObject* userData = NULL, + wxEvtHandler* eventSink = NULL); bool Disconnect(int id = wxID_ANY, - wxEventType eventType = wxEVT_@NULL, - wxObjectEventFunction function = @NULL, - wxObject* userData = @NULL, - wxEvtHandler* eventSink = @NULL); + wxEventType eventType = wxEVT_NULL, + wxObjectEventFunction function = NULL, + wxObject* userData = NULL, + wxEvtHandler* eventSink = NULL); bool Disconnect(int id, int lastId = wxID_ANY, - wxEventType eventType = wxEVT_@NULL, - wxObjectEventFunction function = @NULL, - wxObject* userData = @NULL, - wxEvtHandler* eventSink = @NULL); + wxEventType eventType = wxEVT_NULL, + wxObjectEventFunction function = NULL, + wxObject* userData = NULL, + wxEvtHandler* eventSink = NULL); //@} /** Gets user-supplied client data. @remarks Normally, any extra data the programmer wishes to associate with - the object should be made available by deriving a new - class with new data members. + the object should be made available by deriving a new + class with new data members. - @sa SetClientData() + @see SetClientData() */ void* GetClientData(); /** Get a pointer to the user-supplied client data object. - @sa SetClientObject(), wxClientData + @see SetClientObject(), wxClientData */ wxClientData* GetClientObject(); /** Returns @true if the event handler is enabled, @false otherwise. - @sa SetEvtHandlerEnabled() + @see SetEvtHandlerEnabled() */ bool GetEvtHandlerEnabled(); /** Gets the pointer to the next handler in the chain. - @sa SetNextHandler(), GetPreviousHandler(), - SetPreviousHandler(), wxWindow::PushEventHandler, - wxWindow::PopEventHandler + @see SetNextHandler(), GetPreviousHandler(), + SetPreviousHandler(), wxWindow::PushEventHandler, + wxWindow::PopEventHandler */ wxEvtHandler* GetNextHandler(); /** Gets the pointer to the previous handler in the chain. - @sa SetPreviousHandler(), GetNextHandler(), - SetNextHandler(), wxWindow::PushEventHandler, - wxWindow::PopEventHandler + @see SetPreviousHandler(), GetNextHandler(), + SetNextHandler(), wxWindow::PushEventHandler, + wxWindow::PopEventHandler */ wxEvtHandler* GetPreviousHandler(); @@ -2431,17 +2346,17 @@ public: event handler function(s). @param event - Event to process. + Event to process. @returns @true if a suitable event handler function was found and - executed, and the function did not call wxEvent::Skip. + executed, and the function did not call wxEvent::Skip. @remarks Normally, your application would not call this function: it is - called in the wxWidgets implementation to dispatch - incoming user interface events to the framework (and - application). + called in the wxWidgets implementation to dispatch + incoming user interface events to the framework (and + application). - @sa SearchEventTable() + @see SearchEventTable() */ virtual bool ProcessEvent(wxEvent& event); @@ -2452,12 +2367,12 @@ public: is called. @param event - Event to process. + Event to process. @returns @true if the event was processed, @false if no handler was found - or an exception was thrown. + or an exception was thrown. - @sa wxWindow::HandleWindowEvent + @see wxWindow::HandleWindowEvent */ bool SafelyProcessEvent(wxEvent& event); @@ -2467,18 +2382,17 @@ public: is found. @param table - Event table to be searched. - + Event table to be searched. @param event - Event to be matched against an event table entry. + Event to be matched against an event table entry. @returns @true if a suitable event handler function was found and - executed, and the function did not call wxEvent::Skip. + executed, and the function did not call wxEvent::Skip. @remarks This function looks through the object's event table and tries - to find an entry that will match the event. + to find an entry that will match the event. - @sa ProcessEvent() + @see ProcessEvent() */ virtual bool SearchEventTable(wxEventTable& table, wxEvent& event); @@ -2487,22 +2401,22 @@ public: Sets user-supplied client data. @param data - Data to be associated with the event handler. + Data to be associated with the event handler. @remarks Normally, any extra data the programmer wishes to associate with - the object should be made available by deriving a - new class with new data members. You must not call - this method and SetClientObject on the same class - - only one of them. + the object should be made available by deriving a new + class with new data members. You must not call this + method and SetClientObject on the same class - only one + of them. - @sa GetClientData() + @see GetClientData() */ void SetClientData(void* data); /** Set the client data object. Any previous object will be deleted. - @sa GetClientObject(), wxClientData + @see GetClientObject(), wxClientData */ void SetClientObject(wxClientData* data); @@ -2510,13 +2424,13 @@ public: Enables or disables the event handler. @param enabled - @true if the event handler is to be enabled, @false if it is to be disabled. + @true if the event handler is to be enabled, @false if it is to be disabled. @remarks You can use this function to avoid having to remove the event - handler from the chain, for example when implementing - a dialog editor and changing from edit to test mode. + handler from the chain, for example when implementing a + dialog editor and changing from edit to test mode. - @sa GetEvtHandlerEnabled() + @see GetEvtHandlerEnabled() */ void SetEvtHandlerEnabled(bool enabled); @@ -2524,11 +2438,11 @@ public: Sets the pointer to the next handler. @param handler - Event handler to be set as the next handler. + Event handler to be set as the next handler. - @sa GetNextHandler(), SetPreviousHandler(), - GetPreviousHandler(), wxWindow::PushEventHandler, - wxWindow::PopEventHandler + @see GetNextHandler(), SetPreviousHandler(), + GetPreviousHandler(), wxWindow::PushEventHandler, + wxWindow::PopEventHandler */ void SetNextHandler(wxEvtHandler* handler); @@ -2536,7 +2450,7 @@ public: Sets the pointer to the previous handler. @param handler - Event handler to be set as the previous handler. + Event handler to be set as the previous handler. */ void SetPreviousHandler(wxEvtHandler* handler); }; @@ -2554,8 +2468,8 @@ public: @category{events} @seealso - @ref overview_eventhandlingoverview "Event handling overview", - wxTopLevelWindow::Iconize, wxTopLevelWindow::IsIconized + @ref overview_eventhandlingoverview, wxTopLevelWindow::Iconize, + wxTopLevelWindow::IsIconized */ class wxIconizeEvent : public wxEvent { @@ -2563,7 +2477,7 @@ public: /** Constructor. */ - wxIconizeEvent(int id = 0, bool iconized = @true); + wxIconizeEvent(int id = 0, bool iconized = true); /** Returns @true if the frame has been iconized, @false if it has been @@ -2583,7 +2497,7 @@ public: @category{events} @seealso - wxPoint, @ref overview_eventhandlingoverview "Event handling overview" + wxPoint, @ref overview_eventhandlingoverview */ class wxMoveEvent : public wxEvent { @@ -2608,8 +2522,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 - "Event handling overview". + For more information about events, see the @ref overview_eventhandlingoverview. @b wxPerl note: In wxPerl custom event classes should be derived from @c Wx::PlEvent and @c Wx::PlCommandEvent. @@ -2626,18 +2539,16 @@ public: /** Constructor. Should not need to be used directly by an application. */ - wxEvent(int id = 0, wxEventType eventType = wxEVT_@NULL); + wxEvent(int id = 0, wxEventType eventType = wxEVT_NULL); /** Returns a copy of the event. - Any event that is posted to the wxWidgets event system for later action (via wxEvtHandler::AddPendingEvent or wxPostEvent) must implement this method. All wxWidgets events fully implement this method, but any derived events implemented by the user should also implement this method just in case they (or some event derived from them) are ever posted. - All wxWidgets events implement a copy constructor, so the easiest way of implementing the Clone function is to implement a copy constructor for a new event (call it MyEvent) and then define the Clone function like this: @@ -2720,17 +2631,15 @@ public: the event will not be processed any more. If Skip(@true) is called, the event processing system continues searching for a further handler function for this event, even though it has been processed already in the current handler. - In general, it is recommended to skip all non-command events to allow the default handling to take place. The command events are, however, normally not skipped as usually a single command such as a button click or menu item selection must only be processed by one handler. */ - void Skip(bool skip = @true); + void Skip(bool skip = true); /** Stop the event from propagating to its parent window. - Returns the old propagation level value which may be later passed to ResumePropagation() to allow propagating the event again. @@ -2739,18 +2648,15 @@ public: /** int m_propagationLevel - Indicates how many levels the event can propagate. This member is protected and should typically only be set in the constructors of the derived classes. It may be temporarily changed by StopPropagation() and ResumePropagation() and tested with ShouldPropagate(). - The initial value is set to either @c wxEVENT_PROPAGATE_NONE (by default) meaning that the event shouldn't be propagated at all or to @c wxEVENT_PROPAGATE_MAX (for command events) meaning that it should be propagated as much as necessary. - Any positive number means that the event should be propagated but no more than the given number of times. E.g. the propagation level may be set to 1 to propagate the event to its parent only, but not to its grandparent. @@ -2785,7 +2691,7 @@ public: @category{events} @seealso - wxSize, @ref overview_eventhandlingoverview "Event handling overview" + wxSize, @ref overview_eventhandlingoverview */ class wxSizeEvent : public wxEvent { @@ -2835,18 +2741,18 @@ public: /** Returns the X coordinate of the mouse in client coordinates. */ -#define wxCoord GetX() /* implementation is private */ + wxCoord GetX(); /** Returns the Y coordinate of the mouse in client coordinates. */ -#define wxCoord GetY() /* implementation is private */ + wxCoord GetY(); /** Returns @true if the cursor specified by this event is a valid cursor. @remarks You cannot specify wxNullCursor with this event, as it is not - considered a valid cursor. + considered a valid cursor. */ bool HasCursor(); diff --git a/interface/fdrepdlg.h b/interface/fdrepdlg.h index a83f956a1b..d23caec23e 100644 --- a/interface/fdrepdlg.h +++ b/interface/fdrepdlg.h @@ -21,7 +21,7 @@ public: /** Constuctor used by wxWidgets only. */ - wxFindDialogEvent(wxEventType commandType = wxEVT_@NULL, + wxFindDialogEvent(wxEventType commandType = wxEVT_NULL, int id = 0); /** @@ -129,11 +129,10 @@ public: /** After using default constructor Create() must be called. - - The @e parent and @e data parameters must be non-@NULL. + The @a parent and @a data parameters must be non-@NULL. */ wxFindReplaceDialog(); - wxFindReplaceDialog(wxWindow * parent, + wxFindReplaceDialog(wxWindow* parent, wxFindReplaceData* data, const wxString& title, int style = 0); @@ -146,10 +145,9 @@ public: /** Creates the dialog; use wxWindow::Show to show it on screen. - - The @e parent and @e data parameters must be non-@NULL. + The @a parent and @a data parameters must be non-@NULL. */ - bool Create(wxWindow * parent, wxFindReplaceData* data, + bool Create(wxWindow* parent, wxFindReplaceData* data, const wxString& title, int style = 0); /** diff --git a/interface/ffile.h b/interface/ffile.h index 04a8fbf9e3..b960defa53 100644 --- a/interface/ffile.h +++ b/interface/ffile.h @@ -30,16 +30,14 @@ public: Opens a file with the given file pointer, which has already been opened. @param filename - The filename. - + The filename. @param mode - The mode in which to open the file using standard C strings. - Note that you should use "b" flag if you use binary files under Windows - or the results might be unexpected due to automatic newline conversion done - for the text files. - + The mode in which to open the file using standard C strings. + Note that you should use "b" flag if you use binary files under Windows + or the results might be unexpected due to automatic newline conversion done + for the text files. @param fp - An existing file descriptor, such as stderr. + An existing file descriptor, such as stderr. */ wxFFile(); wxFFile(const wxString& filename, const wxString& mode = "r"); @@ -48,14 +46,12 @@ public: /** Destructor will close the file. - NB: it is not virtual so you should @e not derive from wxFFile! */ ~wxFFile(); /** Attaches an existing file pointer to the wxFFile object. - The descriptor should be already opened and it will be closed by wxFFile object. */ @@ -76,27 +72,24 @@ public: /** Returns @true if the an attempt has been made to read @e past the end of the file. - Note that the behaviour of the file descriptor based class wxFile is different as wxFile::Eof will return @true here as soon as the last byte of the file has been read. - Also note that this method may only be called for opened files and may crash if the file is not opened. - @sa IsOpened() + @see IsOpened() */ -#define bool Eof() /* implementation is private */ + bool Eof(); /** Returns @true if an error has occurred on this file, similar to the standard @c ferror() function. - Please note that this method may only be called for opened files and may crash if the file is not opened. - @sa IsOpened() + @see IsOpened() */ @@ -126,10 +119,9 @@ public: Opens the file, returning @true if successful. @param filename - The filename. - + The filename. @param mode - The mode in which to open the file. + The mode in which to open the file. */ bool Open(const wxString& filename, const wxString& mode = "r"); @@ -138,10 +130,9 @@ public: read. @param buffer - A buffer to receive the data. - + A buffer to receive the data. @param count - The number of bytes to read. + The number of bytes to read. @returns The number of bytes read. */ @@ -149,28 +140,25 @@ public: /** ) - Reads the entire contents of the file into a string. @param str - String to read data into. - + String to read data into. @param conv - Conversion object to use in Unicode build; by default supposes - that file contents is encoded in UTF-8. + Conversion object to use in Unicode build; by default supposes + that file contents is encoded in UTF-8. @returns @true if file was read successfully, @false otherwise. */ - bool ReadAll(wxString * str); + bool ReadAll(wxString* str); /** Seeks to the specified position and returns @true on success. @param ofs - Offset to seek to. - + Offset to seek to. @param mode - One of wxFromStart, wxFromEnd, wxFromCurrent. + One of wxFromStart, wxFromEnd, wxFromCurrent. */ bool Seek(wxFileOffset ofs, wxSeekMode mode = wxFromStart); @@ -180,7 +168,7 @@ public: and returns @true on success. @param ofs - Number of bytes before the end of the file. + Number of bytes before the end of the file. */ bool SeekEnd(wxFileOffset ofs = 0); @@ -191,16 +179,14 @@ public: /** ) - Writes the contents of the string to the file, returns @true on success. - The second argument is only meaningful in Unicode build of wxWidgets when - @e conv is used to convert @e s to multibyte representation. + @e conv is used to convert @a s to multibyte representation. */ bool Write(const wxString& s); /** Returns the file pointer associated with the file. */ -#define FILE * fp() /* implementation is private */ + FILE* fp(); }; diff --git a/interface/file.h b/interface/file.h index 69b44b3934..d019a5a31c 100644 --- a/interface/file.h +++ b/interface/file.h @@ -89,10 +89,9 @@ public: /** Open the temporary file, returns @true on success, @false if an error occurred. - - @e strName is the name of file to be replaced. The temporary file is always - created in the directory where @e strName is. In particular, if - @e strName doesn't include the path, it is created in the current directory + @a strName is the name of file to be replaced. The temporary file is always + created in the directory where @a strName is. In particular, if + @a strName doesn't include the path, it is created in the current directory and the program should have write access to it for the function to succeed. */ bool Open(const wxString& strName); @@ -112,9 +111,8 @@ public: /** Write to the file, return @true on success, @false on failure. - The second argument is only meaningful in Unicode build of wxWidgets when - @e conv is used to convert @e str to multibyte representation. + @a conv is used to convert @a str to multibyte representation. */ bool Write(const wxString& str, const wxMBConv& conv = wxConvUTF8); @@ -150,14 +148,12 @@ public: opened. @param filename - The filename. - + The filename. @param mode - The mode in which to open the file. May be one of read(), write() and + The mode in which to open the file. May be one of read(), write() and wxFile::read_write. - @param fd - An existing file descriptor (see Attach() for the list of predefined + An existing file descriptor (see Attach() for the list of predefined descriptors) */ wxFile(); @@ -168,7 +164,6 @@ public: /** Destructor will close the file. - @b NB: it is not virtual so you should not use wxFile polymorphically. */ ~wxFile(); @@ -185,7 +180,6 @@ public: (and have symbolic names of @b wxFile::fd_stdin, @b wxFile::fd_stdout and @b wxFile::fd_stderr). - The descriptor should be already opened and it will be closed by wxFile object. */ @@ -201,7 +195,7 @@ public: @true will ensure it is overwritten. */ - bool Create(const wxString& filename, bool overwrite = @false, + bool Create(const wxString& filename, bool overwrite = false, int access = wxS_DEFAULT); /** @@ -213,14 +207,12 @@ public: /** Returns @true if the end of the file has been reached. - Note that the behaviour of the file pointer based class wxFFile is different as wxFFile::Eof will return @true here only if an attempt has been made to read @e past the last byte of the file, while wxFile::Eof() will return @true even before such attempt is made if the file pointer is at the last position in the file. - Note also that this function doesn't work on unseekable file descriptors (examples include pipes, terminals and sockets under Unix) and an attempt to use it will result in an error message in such case. So, to read the entire @@ -228,7 +220,7 @@ public: Read() repeatedly and tests its return condition instead of using Eof() as this will not work for special files under Unix. */ -#define bool Eof() /* implementation is private */ + bool Eof(); /** Returns @true if the given name specifies an existing regular file (not a @@ -238,7 +230,6 @@ public: /** Flushes the file descriptor. - Note that Flush() is not implemented on some Windows compilers due to a missing fsync function, which reduces the usefulness of this function (it can still be called but it will do nothing on unsupported compilers). @@ -264,10 +255,9 @@ public: Opens the file, returning @true if successful. @param filename - The filename. - + The filename. @param mode - The mode in which to open the file. May be one of read(), write() and + The mode in which to open the file. May be one of read(), write() and wxFile::read_write. */ bool Open(const wxString& filename, @@ -286,13 +276,12 @@ public: Seeks to the specified position. @param ofs - Offset to seek to. - + Offset to seek to. @param mode - One of wxFromStart, wxFromEnd, wxFromCurrent. + One of wxFromStart, wxFromEnd, wxFromCurrent. @returns The actual offset position achieved, or wxInvalidOffset on - failure. + failure. */ wxFileOffset Seek(wxFileOffset ofs, wxSeekMode mode = wxFromStart); @@ -303,10 +292,10 @@ public: bytes before the end. @param ofs - Number of bytes before the end of the file. + Number of bytes before the end of the file. @returns The actual offset position achieved, or wxInvalidOffset on - failure. + failure. */ wxFileOffset SeekEnd(wxFileOffset ofs = 0); @@ -319,10 +308,8 @@ public: /** Writes the contents of the string to the file, returns @true on success. - The second argument is only meaningful in Unicode build of wxWidgets when - @e conv is used to convert @e s to multibyte representation. - + @a conv is used to convert @a s to multibyte representation. Note that this method only works with @c NUL-terminated strings, if you want to write data with embedded @c NULs to the file you should use the other @ref write() "Write() overload". @@ -332,5 +319,5 @@ public: /** Returns the file descriptor associated with the file. */ -#define int fd() /* implementation is private */ + int fd(); }; diff --git a/interface/fileconf.h b/interface/fileconf.h index f8810f2046..79838869f6 100644 --- a/interface/fileconf.h +++ b/interface/fileconf.h @@ -31,32 +31,29 @@ class wxFileConfig : public wxConfigBase public: /** ) - Read the config data from the specified stream instead of the associated file, as usual. - @sa Save() + @see Save() */ wxFileConfig(wxInputStream& is); /** Return the full path to the file which would be used by wxFileConfig as global, - system-wide, file if it were constructed with @e basename as "global + system-wide, file if it were constructed with @a basename as "global filename'' parameter in the constructor. Notice that this function cannot be - used if @e basename is already a full path name. + used if @a basename is already a full path name. */ static wxFileName GetGlobalFile(const wxString& basename); /** Return the full path to the file which would be used by wxFileConfig as local, - user-specific, file if it were constructed with @e basename as "local + user-specific, file if it were constructed with @a basename as "local filename'' parameter in the constructor. - - @e style has the same meaning as in @ref wxConfigBase::ctor constructor + @a style has the same meaning as in @ref wxConfigBase::ctor constructor and can contain any combination of styles but only wxCONFIG_USE_SUBDIR bit is examined by this function. - - Notice that this function cannot be used if @e basename is already a full + Notice that this function cannot be used if @a basename is already a full path name. */ static wxFileName GetLocalFile(const wxString& basename, @@ -64,17 +61,15 @@ public: /** ) - Saves all config data to the given stream, returns @true if data was saved successfully or @false on error. - Note the interaction of this function with the internal "dirty flag'': the data is saved unconditionally, i.e. even if the object is not dirty. However after saving it successfully, the dirty flag is reset so no changes will be written back to the file this object is associated with until you change its contents again. - @sa wxConfigBase::Flush + @see wxConfigBase::Flush */ bool Save(wxOutputStream& os); @@ -83,10 +78,9 @@ public: create a config file which is not readable by other users (useful if it stores some sensitive information, such as passwords), you could use @c SetUmask(0077). - This function doesn't do anything on non-Unix platforms. - @sa wxCHANGE_UMASK + @see wxCHANGE_UMASK */ void SetUmask(int mode); }; diff --git a/interface/filectrl.h b/interface/filectrl.h index d96cbbc432..a24a4822a0 100644 --- a/interface/filectrl.h +++ b/interface/filectrl.h @@ -42,40 +42,32 @@ public: //@{ /** @param parent - Parent window, must not be non-@NULL. - + Parent window, must not be non-@NULL. @param id - The identifier for the control. - + The identifier for the control. @param defaultDirectory - The initial directory shown in the control. Must be - a valid path to a directory or the empty string. - In case it is the empty string, the current working directory is used. - + The initial directory shown in the control. Must be + a valid path to a directory or the empty string. + In case it is the empty string, the current working directory is used. @param defaultFilename - The default filename, or the empty string. - + The default filename, or the empty string. @param wildcard - A wildcard specifying which files can be selected, - such as "*.*" or "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif". - + A wildcard specifying which files can be selected, + such as "*.*" or "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif". @param style - The window style, see wxFC_* flags. - + The window style, see wxFC_* flags. @param pos - Initial position. - + Initial position. @param size - Initial size. - + Initial size. @param name - Control name. + Control name. @returns @true if the control was successfully created or @false if - creation failed. + creation failed. */ wxFileCtrl(); - wxFileCtrl(wxWindow * parent, wxWindowID id, + wxFileCtrl(wxWindow* parent, wxWindowID id, const wxString& defaultDirectory = wxEmptyString, const wxString& defaultFilename = wxEmptyString, const wxPoint& wildCard = wxFileSelectorDefaultWildcardStr, @@ -88,7 +80,7 @@ public: /** Create function for two-step construction. See wxFileCtrl() for details. */ - bool Create(wxWindow * parent, wxWindowID id, + bool Create(wxWindow* parent, wxWindowID id, const wxString& defaultDirectory = wxEmptyString, const wxString& defaultFilename = wxEmptyString, const wxPoint& wildCard = wxFileSelectorDefaultWildcardStr, @@ -111,7 +103,7 @@ public: wxString GetFilename(); /** - Fills the array @e filenames with the filenames only of selected items. This + Fills the array @a filenames with the filenames only of selected items. This function should only be used with the controls having the @c wxFC_MULTIPLE style, use GetFilename() for the others. @@ -133,7 +125,7 @@ public: wxString GetPath(); /** - Fills the array @e paths with the full paths of the files chosen. This + Fills the array @a paths with the full paths of the files chosen. This function should be used with the controls having the @c wxFC_MULTIPLE style, use GetPath() otherwise. @@ -167,7 +159,6 @@ public: /** Sets the wildcard, which can contain multiple file types, for example: - "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" */ void SetWildcard(const wxString& wildCard); diff --git a/interface/filedlg.h b/interface/filedlg.h index 8d84bf06a2..09d0caae3b 100644 --- a/interface/filedlg.h +++ b/interface/filedlg.h @@ -51,34 +51,26 @@ public: Constructor. Use ShowModal() to show the dialog. @param parent - Parent window. - + Parent window. @param message - Message to show on the dialog. - + Message to show on the dialog. @param defaultDir - The default directory, or the empty string. - + The default directory, or the empty string. @param defaultFile - The default filename, or the empty string. - + The default filename, or the empty string. @param wildcard - A wildcard, such as "*.*" or "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif". - - Note that the native Motif dialog has some limitations with respect to - wildcards; see the Remarks section above. - + A wildcard, such as "*.*" or "BMP files (*.bmp)|*.bmp|GIF files + (*.gif)|*.gif". + Note that the native Motif dialog has some limitations with respect to + wildcards; see the Remarks section above. @param style - A dialog style. See wxFD_* styles for more info. - + A dialog style. See wxFD_* styles for more info. @param pos - Dialog position. Not implemented. - + Dialog position. Not implemented. @param size - Dialog size. Not implemented. - + Dialog size. Not implemented. @param name - Dialog name. Not implemented. + Dialog name. Not implemented. */ wxFileDialog(wxWindow* parent, const wxString& message = "Choose a file", @@ -114,10 +106,9 @@ public: wxString GetFilename(); /** - Fills the array @e filenames with the names of the files chosen. This + Fills the array @a filenames with the names of the files chosen. This function should only be used with the dialogs which have @c wxFD_MULTIPLE style, use GetFilename() for the others. - Note that under Windows, if the user selects shortcuts, the filenames include paths, since the application cannot determine the full path of each referenced file by appending the directory containing the shortcuts @@ -145,7 +136,7 @@ public: wxString GetPath(); /** - Fills the array @e paths with the full paths of the files chosen. This + Fills the array @a paths with the full paths of the files chosen. This function should only be used with the dialogs which have @c wxFD_MULTIPLE style, use GetPath() for the others. */ @@ -164,12 +155,10 @@ public: /** Customize file dialog by adding extra window, which is typically placed below the list of files and above the buttons. - SetExtraControlCreator can be called only once, before calling ShowModal(). The @c creator function should take pointer to parent window (file dialog) and should return a window allocated with operator new. - Supported platforms: wxGTK, wxUniv. */ bool SetExtraControlCreator(t_extraControlCreator creator); @@ -197,9 +186,7 @@ public: /** Sets the wildcard, which can contain multiple file types, for example: - "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" - Note that the native Motif dialog has some limitations with respect to wildcards; see the Remarks section above. */ @@ -229,20 +216,20 @@ public: wxFD_MULTIPLE can only be used with wxFileDialog and not here as this function only returns a single file name. - Both the Unix and Windows versions implement a wildcard filter. Typing a filename containing wildcards (*, ?) in the filename text item, and clicking on Ok, will result in only those files matching the pattern being displayed. - The wildcard may be a specification for multiple types of file with a description for each, such as: + @code "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" @endcode The application must check for an empty return value (the user pressed Cancel). For example: + @code wxString filename = wxFileSelector("Choose a file to open"); if ( !filename.empty() ) @@ -259,7 +246,7 @@ wxString wxFileSelector(const wxString& message, const wxString& default_extension = "", const wxString& wildcard = ".", int flags = 0, - wxWindow * parent = @NULL, + wxWindow* parent = NULL, int x = -1, int y = -1); diff --git a/interface/filefn.h b/interface/filefn.h index 9f3486476a..9e239fefdc 100644 --- a/interface/filefn.h +++ b/interface/filefn.h @@ -40,15 +40,12 @@ public: The first form adds the given directory to the path list, if the path is not already in the list. If the path cannot be normalized for some reason, it returns @false. - The second form just calls the first form on all elements of the given array. - - The @e path is always considered a directory but no existence checks will be + The @a path is always considered a directory but no existence checks will be done on it (because if it doesn't exist, it could be created later and thus result a valid path when FindValidPath() is called). - @b Note: if the given path is relative, it won't be made absolute before adding it (this is why FindValidPath() may return relative paths). @@ -82,15 +79,12 @@ public: Searches the given file in all paths stored in this class. The first path which concatenated to the given string points to an existing file (see @ref wxFile::exists wxFileExists) is returned. - If the file wasn't found in any of the stored paths, an empty string is returned. - The given string must be a file name, eventually with a path prefix (if the path prefix is absolute, only its name will be searched); i.e. it must not end with a directory separator (see wxFileName::GetPathSeparator) otherwise an assertion will fail. - The returned path may be relative to the current working directory. Note in fact that wxPathList can be used to store both relative and absolute paths so that @@ -108,13 +102,13 @@ public: /** This function returns the total number of bytes and number of free bytes on - the disk containing the directory @e path (it should exist). Both - @e total and @e free parameters may be @NULL if the corresponding + the disk containing the directory @a path (it should exist). Both + @a total and @a free parameters may be @NULL if the corresponding information is not needed. */ bool wxGetDiskSpace(const wxString& path, - wxLongLong total = @NULL, - wxLongLong free = @NULL); + wxLongLong total = NULL, + wxLongLong free = NULL); /** Returns the Windows directory under Windows; on other platforms returns the @@ -128,7 +122,7 @@ wxString wxGetOSDirectory(); The arrays will contain an equal number of items found before the error. On platforms where native dialogs handle only one filter per entry, entries in arrays are automatically adjusted. - @e wildCard is in the form: + @a wildCard is in the form: @code "All files (*)|*|Image Files (*.jpeg *.png)|*.jpg;*.png" @@ -140,40 +134,35 @@ int wxParseCommonDialogsFilter(const wxString& wildCard, /** This function is deprecated, use wxFileName instead. - Converts a Unix to a DOS filename by replacing forward slashes with backslashes. */ -void wxUnix2DosFilename(wxChar * s); +void wxUnix2DosFilename(wxChar* s); /** - Returns @true if @e dirname exists and is a directory. + Returns @true if @a dirname exists and is a directory. */ bool wxDirExists(const wxString& dirname); /** @b NB: This function is obsolete, please use wxFileName::SplitPath instead. - This function splits a full file name into components: the path (including possible disk/drive specification under Windows), the base name and the extension. Any of the output parameters - (@e path, @e name or @e ext) may be @NULL if you are not interested in the value + (@e path, @a name or @e ext) may be @NULL if you are not interested in the value of a particular component. - wxSplitPath() will correctly handle filenames with both DOS and Unix path separators under Windows, however it will not consider backslashes as path separators under Unix (where backslash is a valid character in a filename). - - On entry, @e fullname should be non-@NULL (it may be empty though). - - On return, @e path contains the file path (without the trailing separator), @e + On entry, @a fullname should be non-@NULL (it may be empty though). + On return, @a path contains the file path (without the trailing separator), @e name - contains the file name and @e ext contains the file extension without leading + contains the file name and @a ext contains the file extension without leading dot. All three of them may be empty if the corresponding component is. The old contents of the @@ -181,23 +170,21 @@ bool wxDirExists(const wxString& dirname); pointers are not @NULL). */ -void wxSplitPath(const wxString& fullname, wxString * path, - wxString * name, - wxString * ext); +void wxSplitPath(const wxString& fullname, wxString* path, + wxString* name, + wxString* ext); /** Under Unix this macro changes the current process umask to the given value, unless it is equal to -1 in which case nothing is done, and restores it to the original value on scope exit. It works by declaring a variable which sets - umask to @e mask in its constructor and restores it in its destructor. - + umask to @a mask in its constructor and restores it in its destructor. Under other platforms this macro expands to nothing. */ #define wxCHANGE_UMASK(int mask) /* implementation is private */ /** Returns time of last modification of given file. - The function returns @c (time_t)-1 if an error occurred (e.g. file not found). */ @@ -207,34 +194,31 @@ time_t wxFileModificationTime(const wxString& filename); /** @b NB: This function is obsolete, please use wxFileName::SplitPath instead. - Returns the filename for a full path. The second form returns a pointer to temporary storage that should not be deallocated. */ wxString wxFileNameFromPath(const wxString& path); -char * wxFileNameFromPath(char * path); +char* wxFileNameFromPath(char* path); //@} /** - Renames @e file1 to @e file2, returning @true if successful. - - If @e overwrite parameter is @true (default), the destination file is - overwritten if it exists, but if @e overwrite is @false, the functions fails + Renames @a file1 to @e file2, returning @true if successful. + If @a overwrite parameter is @true (default), the destination file is + overwritten if it exists, but if @a overwrite is @false, the functions fails in this case. */ bool wxRenameFile(const wxString& file1, const wxString& file2, - bool overwrite = @true); + bool overwrite = true); /** - Copies @e file1 to @e file2, returning @true if successful. If - @e overwrite parameter is @true (default), the destination file is overwritten - if it exists, but if @e overwrite is @false, the functions fails in this + Copies @a file1 to @e file2, returning @true if successful. If + @a overwrite parameter is @true (default), the destination file is overwritten + if it exists, but if @a overwrite is @false, the functions fails in this case. - This function supports resources forks under Mac OS. */ bool wxCopyFile(const wxString& file1, const wxString& file2, - bool overwrite = @true); + bool overwrite = true); /** Returns @true if the file exists and is a plain file. @@ -242,7 +226,7 @@ bool wxCopyFile(const wxString& file1, const wxString& file2, bool wxFileExists(const wxString& filename); /** - Returns @true if the @e pattern matches the @e text; if @e dot_special is @true, + Returns @true if the @a pattern matches the @e text; if @a dot_special is @true, filenames beginning with a dot are not matched with wildcard characters. See wxIsWild. */ @@ -251,14 +235,12 @@ bool wxMatchWild(const wxString& pattern, const wxString& text, /** @b NB: This function is deprecated: use wxGetCwd instead. - Copies the current working directory into the buffer if supplied, or copies the working directory into new storage (which you must delete yourself) if the buffer is @NULL. - - @e sz is the size of the buffer if supplied. + @a sz is the size of the buffer if supplied. */ -wxString wxGetWorkingDirectory(char * buf=@NULL, int sz=1000); +wxString wxGetWorkingDirectory(char* buf = NULL, int sz = 1000); /** Returns the directory part of the filename. @@ -279,10 +261,10 @@ wxString wxGetCwd(); Converts a DOS to a Unix filename by replacing backslashes with forward slashes. */ -void wxDos2UnixFilename(wxChar * s); +void wxDos2UnixFilename(wxChar* s); /** - Concatenates @e file1 and @e file2 to @e file3, returning + Concatenates @a file1 and @a file2 to @e file3, returning @true if successful. */ bool wxConcatFiles(const wxString& file1, const wxString& file2, @@ -295,15 +277,14 @@ bool wxRemoveFile(const wxString& file); /** Sets the current working directory, returning @true if the operation succeeded. - Under MS Windows, the current drive is also changed if @e dir contains a drive + Under MS Windows, the current drive is also changed if @a dir contains a drive specification. */ bool wxSetWorkingDirectory(const wxString& dir); /** Makes the directory @e dir, returning @true if successful. - - @e perm is the access mask for the directory for the systems on which it is + @a perm is the access mask for the directory for the systems on which it is supported (Unix) and doesn't have any effect on the other ones. */ bool wxMkdir(const wxString& dir, int perm = 0777); @@ -316,7 +297,6 @@ bool wxIsAbsolutePath(const wxString& filename); /** Returns the next file that matches the path passed to wxFindFirstFile. - See wxFindFirstFile for an example. */ wxString wxFindNextFile(); @@ -332,6 +312,7 @@ wxString wxFindFirstFile(const wxString& spec, int flags = 0); //@{ /** Returns the type of an open file. Possible return values are: + @code enum wxFileKind { @@ -343,7 +324,7 @@ wxString wxFindFirstFile(const wxString& spec, int flags = 0); @endcode */ wxFileKind wxGetFileKind(int fd); -wxFileKind wxGetFileKind(FILE * fp); +wxFileKind wxGetFileKind(FILE* fp); //@} //@{ @@ -352,20 +333,18 @@ wxFileKind wxGetFileKind(FILE * fp); wxFileName::CreateTempFileName instead. */ -char * wxGetTempFileName(const wxString& prefix, char * buf=@NULL); +char* wxGetTempFileName(const wxString& prefix, char* buf = NULL); bool wxGetTempFileName(const wxString& prefix, wxString& buf); //@} /** Removes the directory @e dir, returning @true if successful. Does not work under VMS. - - The @e flags parameter is reserved for future use. - + The @a flags parameter is reserved for future use. Please notice that there is also a wxRmDir() function which simply wraps the standard POSIX rmdir() function and so return an integer error code instead of a boolean value (but otherwise is currently identical to wxRmdir), don't confuse these two functions. */ -bool wxRmdir(const wxString& dir, int flags=0); +bool wxRmdir(const wxString& dir, int flags = 0); diff --git a/interface/filename.h b/interface/filename.h index b62606dc9f..ed6d6eebd8 100644 --- a/interface/filename.h +++ b/interface/filename.h @@ -120,9 +120,9 @@ public: /** Makes this object refer to the current working directory on the specified - volume (or current volume if @e volume is empty). + volume (or current volume if @a volume is empty). - @sa GetCwd() + @see GetCwd() */ static void AssignCwd(const wxString& volume = wxEmptyString); @@ -145,7 +145,7 @@ public: @ref isok() invalid state. */ void AssignTempFileName(const wxString& prefix, - wxFile * fileTemp = @NULL); + wxFile* fileTemp = NULL); /** Reset all components to default, uninitialized state. @@ -156,36 +156,33 @@ public: Removes the extension from the file name resulting in a file name with no trailing dot. - @sa SetExt(), SetEmptyExt() + @see SetExt(), SetEmptyExt() */ void SetClearExt(); /** Returns a temporary file name starting with the given @e prefix. If - the @e prefix is an absolute path, the temporary file is created in this + the @a prefix is an absolute path, the temporary file is created in this directory, otherwise it is created in the default system directory for the temporary files or in the current directory. - If the function succeeds, the temporary file is actually created. If - @e fileTemp is not @NULL, this file will be opened using the name of + @a fileTemp is not @NULL, this file will be opened using the name of the temporary file. When possible, this is done in an atomic way ensuring that no race condition occurs between the temporary file name generation and opening it which could often lead to security compromise on the multiuser systems. - If @e fileTemp is @NULL, the file is only created, but not opened. - + If @a fileTemp is @NULL, the file is only created, but not opened. Under Unix, the temporary file will have read and write permissions for the owner only to minimize the security problems. @param prefix - Prefix to use for the temporary file name construction - + Prefix to use for the temporary file name construction @param fileTemp - The file to open or @NULL to just get the name + The file to open or @NULL to just get the name @returns The full temporary file name or an empty string on error. */ static wxString CreateTempFileName(const wxString& prefix, - wxFile * fileTemp = @NULL); + wxFile* fileTemp = NULL); //@{ /** @@ -197,7 +194,7 @@ public: /** Returns the object corresponding to the directory with the given name. - The @e dir parameter may have trailing path separator or not. + The @a dir parameter may have trailing path separator or not. */ static wxFileName DirName(const wxString& dir, wxPathFormat format = wxPATH_NATIVE); @@ -205,7 +202,6 @@ public: /** These functions allow to examine and modify the individual directories of the path: - AppendDir() InsertDir() @@ -216,10 +212,8 @@ public: RemoveDir() RemoveLastDir() - To change the components of the file name individually you can use the following functions: - GetExt() GetName() @@ -246,7 +240,6 @@ public: /** You can initialize a wxFileName instance using one of the following functions: - @ref wxfilename() "wxFileName constructors" Assign() @@ -279,10 +272,8 @@ public: for example, the volume name is always empty under Unix, but if they are all empty simultaneously, the filename object is considered to be in an invalid state and IsOk() returns @false for it. - File names can be case-sensitive or not, the function IsCaseSensitive() allows to determine this. - The rules for determining whether the file name is absolute or relative also depend on the file name format and the only portable way to answer this question is to use IsAbsolute() or @@ -290,12 +281,10 @@ public: refers to the current working directory on drive X. Therefore, a wxFileName instance constructed from for example "X:dir/file.ext" treats the portion beyond drive separator as being relative to that directory. - To ensure that the filename is absolute, you may use MakeAbsolute(). There is also an inverse function MakeRelativeTo() which undoes what @ref normalize() Normalize(wxPATH_NORM_DOTS) does. - Other functions returning information about the file format provided by this class are GetVolumeSeparator(), IsPathSeparator(). @@ -308,12 +297,9 @@ public: FileExists() can be used to test whether a file with such name exists and DirExists() can be used to test for directory existence. - File names should be compared using SameAs() method or @ref operatorequal() "operator ==". - For testing basic access modes, you can use: - IsDirWritable() IsDirReadable() @@ -330,7 +316,7 @@ public: /** Returns @true if the file with this name exists. - @sa DirExists() + @see DirExists() */ bool FileExists(); static bool FileExists(const wxString& file); @@ -349,9 +335,9 @@ public: current volume. @returns The string containing the current working directory or an empty - string on error. + string on error. - @sa AssignCwd() + @see AssignCwd() */ static wxString GetCwd(const wxString& volume = ""); @@ -401,12 +387,10 @@ public: Returns the size of this file (first form) or the given number of bytes (second form) in a human-readable form. - If the size could not be retrieved the @c failmsg string is returned (first form). If @c bytes is @c wxInvalidSize or zero, then @c nullsize is returned (second form). - In case of success, the returned string is a floating-point number with @c precision decimal digits followed by the size unit (B, kB, MB, GB, TB: respectively bytes, kilobytes, @@ -432,7 +416,7 @@ public: /** Returns the name part of the filename (without extension). - @sa GetFullName() + @see GetFullName() */ wxString GetName(); @@ -440,17 +424,14 @@ public: Returns the path part of the filename (without the name or extension). The possible flags values are: - @b wxPATH_GET_VOLUME - Return the path with the volume (does nothing for the filename formats without volumes), otherwise the path without volume part is returned. @b wxPATH_GET_SEPARATOR - Return the path with the trailing separator, if this flag is not given there will be no separator at the end of the path. @@ -464,7 +445,7 @@ public: are two of them and the native one, i.e. the backslash is returned by this method. - @sa GetPathSeparators() + @see GetPathSeparators() */ static wxChar GetPathSeparator(wxPathFormat format = wxPATH_NATIVE); @@ -474,7 +455,7 @@ public: DOS and Windows both @c '/' and @c '\' may be used as separators. - @sa GetPathSeparator() + @see GetPathSeparator() */ static wxString GetPathSeparators(wxPathFormat format = wxPATH_NATIVE); @@ -488,7 +469,6 @@ public: /** Returns the path with the trailing separator, useful for appending the name to the given path. - This is the same as calling GetPath() @c (wxPATH_GET_VOLUME | wxPATH_GET_SEPARATOR, format). */ @@ -524,13 +504,11 @@ public: under Windows and the inode change time under Unix (as it is impossible to retrieve the real file creation time there anyhow) which can also be changed by many operations after the file creation. - If no filename or extension is specified in this instance of wxFileName (and therefore IsDir() returns @true) then this function will return the directory times of the path specified by GetPath(), otherwise the file times of the file specified by GetFullPath(). - Any of the pointers may be @NULL if the corresponding time is not needed. @@ -647,7 +625,7 @@ public: Clear() may reset the object to the uninitialized, invalid state (the former only do it on failure). */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** Returns @true if the char is a path separator for this format. @@ -686,7 +664,7 @@ public: @c wxFileName::Normalize(wxPATH_NORM_DOTS | wxPATH_NORM_ABSOLUTE | wxPATH_NORM_TILDE, cwd, format). - @sa MakeRelativeTo(), Normalize(), IsAbsolute() + @see MakeRelativeTo(), Normalize(), IsAbsolute() */ bool MakeAbsolute(const wxString& cwd = wxEmptyString, wxPathFormat format = wxPATH_NATIVE); @@ -699,18 +677,17 @@ public: file if the current directory were pathBase. pathBase - the directory to use as root, current directory is used by - default - + the directory to use as root, current directory is used by + default @param format - the file name format, native by default + the file name format, native by default @returns @true if the file name has been changed, @false if we failed to do - anything with it (currently this only happens if the - file name is on a volume different from the volume - specified by pathBase). + anything with it (currently this only happens if the + file name is on a volume different from the volume + specified by pathBase). - @sa Normalize() + @see Normalize() */ bool MakeRelativeTo(const wxString& pathBase = wxEmptyString, wxPathFormat format = wxPATH_NATIVE); @@ -718,18 +695,16 @@ public: //@{ /** @param dir - the directory to create - + the directory to create @param parm - the permissions for the newly created directory - + the permissions for the newly created directory @param flags - if the flags contain wxPATH_MKDIR_FULL flag, - try to create each directory in the path and also don't return an error - if the target directory already exists. + if the flags contain wxPATH_MKDIR_FULL flag, + try to create each directory in the path and also don't return an error + if the target directory already exists. @returns Returns @true if the directory was successfully created, @false - otherwise. + otherwise. */ bool Mkdir(int perm = 0777, int flags = 0); static bool Mkdir(const wxString& dir, int perm = 0777, @@ -742,56 +717,103 @@ public: variables will be expanded in it. @param flags - The kind of normalization to do with the file name. It can be - any or-combination of the following constants: + The kind of normalization to do with the file name. It can be + any or-combination of the following constants: + + + + + - wxPATH_NORM_ENV_VARS + wxPATH_NORM_ENV_VARS - replace env vars with their values - wxPATH_NORM_DOTS + replace env vars with their values - squeeze all .. and . when possible; if there are too many .. and thus they + + + + + wxPATH_NORM_DOTS + + + + + squeeze all .. and . when possible; if there are too many .. and thus they cannot be all removed, @false will be returned - wxPATH_NORM_CASE - if filesystem is case insensitive, transform to lower case - wxPATH_NORM_ABSOLUTE + wxPATH_NORM_CASE - make the path absolute prepending cwd - wxPATH_NORM_LONG - make the path the long form + if filesystem is case insensitive, transform to lower case - wxPATH_NORM_SHORTCUT - resolve if it is a shortcut (Windows only) - wxPATH_NORM_TILDE + wxPATH_NORM_ABSOLUTE - replace ~ and ~user (Unix only) - wxPATH_NORM_ALL - all of previous flags except wxPATH_NORM_CASE + make the path absolute prepending cwd + - @param cwd - If not empty, this directory will be used instead of current - working directory in normalization (see wxPATH_NORM_ABSOLUTE). + + + wxPATH_NORM_LONG + + + + + make the path the long form + + + + + + wxPATH_NORM_SHORTCUT + + + + + resolve if it is a shortcut (Windows only) + + + + + + wxPATH_NORM_TILDE + + + + + replace ~ and ~user (Unix only) + + + + + + wxPATH_NORM_ALL + + + + + all of previous flags except wxPATH_NORM_CASE + @param cwd + If not empty, this directory will be used instead of current + working directory in normalization (see wxPATH_NORM_ABSOLUTE). @param format - The file name format to use when processing the paths, native by default. + The file name format to use when processing the paths, native by default. @returns @true if normalization was successfully or @false otherwise. */ @@ -805,7 +827,6 @@ public: in the same way. For example, the access time under Windows has a resolution of one day (so it is really the access date and not time). The access time may be updated when the file is executed or not depending on the platform. - GetModificationTime() GetTimes() @@ -813,9 +834,7 @@ public: SetTimes() Touch() - Other file system operations functions are: - Mkdir() Rmdir() @@ -831,7 +850,7 @@ public: /** Removes the specified directory component from the path. - @sa GetDirCount() + @see GetDirCount() */ void RemoveDir(size_t pos); @@ -867,7 +886,7 @@ public: This is different from having no extension at all as the file name will have a trailing dot after a call to this method. - @sa SetExt(), ClearExt() + @see SetExt(), ClearExt() */ void SetEmptyExt(); @@ -877,7 +896,7 @@ public: name without a trailing dot, unlike a call to SetEmptyExt(). - @sa SetEmptyExt(), ClearExt() + @see SetEmptyExt(), ClearExt() */ void SetExt(const wxString& ext); @@ -889,7 +908,7 @@ public: /** Sets the name part (without extension). - @sa SetFullName() + @see SetFullName() */ void SetName(const wxString& name); @@ -911,24 +930,22 @@ public: This function splits a full file name into components: the volume (with the first version) path (including the volume in the second version), the base name and the extension. Any of the output parameters (@e volume, @e path, - @e name or @e ext) may be @NULL if you are not interested in the - value of a particular component. Also, @e fullpath may be empty on entry. - - On return, @e path contains the file path (without the trailing separator), - @e name contains the file name and @e ext contains the file extension + @a name or @e ext) may be @NULL if you are not interested in the + value of a particular component. Also, @a fullpath may be empty on entry. + On return, @a path contains the file path (without the trailing separator), + @a name contains the file name and @a ext contains the file extension without leading dot. All three of them may be empty if the corresponding component is. The old contents of the strings pointed to by these parameters will be overwritten in any case (if the pointers are not @NULL). - Note that for a filename "foo.'' the extension is present, as indicated by the trailing dot, but empty. If you need to cope with such cases, you should use - @e hasExt instead of relying on testing whether @e ext is empty or not. + @a hasExt instead of relying on testing whether @a ext is empty or not. */ static void SplitPath(const wxString& fullpath, wxString* volume, wxString* path, wxString* name, wxString* ext, - bool hasExt = @NULL, + bool hasExt = NULL, wxPathFormat format = wxPATH_NATIVE); static void SplitPath(const wxString& fullpath, wxString* volume, @@ -944,10 +961,10 @@ public: //@} /** - Splits the given @e fullpath into the volume part (which may be empty) and + Splits the given @a fullpath into the volume part (which may be empty) and the pure path part, not containing any volume. - @sa SplitPath() + @see SplitPath() */ static void SplitVolume(const wxString& fullpath, wxString* volume, diff --git a/interface/filepicker.h b/interface/filepicker.h index 41ab03a379..fdca7c023f 100644 --- a/interface/filepicker.h +++ b/interface/filepicker.h @@ -55,7 +55,7 @@ public: Initializes the object and calls Create() with all the parameters. */ - wxFilePickerCtrl(wxWindow * parent, wxWindowID id, + wxFilePickerCtrl(wxWindow* parent, wxWindowID id, const wxString& path = wxEmptyString, const wxString& message = "Select a file", const wxString& wildcard = ".", @@ -67,41 +67,32 @@ public: /** @param parent - Parent window, must not be non-@NULL. - + Parent window, must not be non-@NULL. @param id - The identifier for the control. - + The identifier for the control. @param path - The initial file shown in the control. Must be a valid path to a file or the - empty string. - + The initial file shown in the control. Must be a valid path to a file or + the empty string. @param message - The message shown to the user in the wxFileDialog shown by the control. - + The message shown to the user in the wxFileDialog shown by the control. @param wildcard - A wildcard which defines user-selectable files (use the same syntax as for + A wildcard which defines user-selectable files (use the same syntax as for wxFileDialog's wildcards). - @param pos - Initial position. - + Initial position. @param size - Initial size. - + Initial size. @param style - The window style, see wxFLP_* flags. - + The window style, see wxFLP_* flags. @param validator - Validator which can be used for additional date checks. - + Validator which can be used for additional date checks. @param name - Control name. + Control name. @returns @true if the control was successfully created or @false if - creation failed. + creation failed. */ - bool Create(wxWindow * parent, wxWindowID id, + bool Create(wxWindow* parent, wxWindowID id, const wxString& path = wxEmptyString, const wxString& message = "Select a file", const wxString& wildcard = ".", @@ -126,14 +117,14 @@ public: This method does the same thing as SetPath() but takes a wxFileName object instead of a string. */ - void SetFileName(const wxFileName & filename); + void SetFileName(const wxFileName& filename); /** Sets the absolute path of the currently selected file. This must be a valid file if the @c wxFLP_FILE_MUST_EXIST style was given. */ - void SetPath(const wxString & filename); + void SetPath(const wxString& filename); }; @@ -182,7 +173,7 @@ public: Initializes the object and calls Create() with all the parameters. */ - wxDirPickerCtrl(wxWindow * parent, wxWindowID id, + wxDirPickerCtrl(wxWindow* parent, wxWindowID id, const wxString& path = wxEmptyString, const wxString& message = "Select a folder", const wxPoint& pos = wxDefaultPosition, @@ -193,37 +184,29 @@ public: /** @param parent - Parent window, must not be non-@NULL. - + Parent window, must not be non-@NULL. @param id - The identifier for the control. - + The identifier for the control. @param path - The initial directory shown in the control. Must be a valid path to a directory - or the empty string. - + The initial directory shown in the control. Must be a valid path to a + directory or the empty string. @param message - The message shown to the user in the wxDirDialog shown by the control. - + The message shown to the user in the wxDirDialog shown by the control. @param pos - Initial position. - + Initial position. @param size - Initial size. - + Initial size. @param style - The window style, see wxDIRP_* flags. - + The window style, see wxDIRP_* flags. @param validator - Validator which can be used for additional date checks. - + Validator which can be used for additional date checks. @param name - Control name. + Control name. @returns @true if the control was successfully created or @false if - creation failed. + creation failed. */ - bool Create(wxWindow * parent, wxWindowID id, + bool Create(wxWindow* parent, wxWindowID id, const wxString& path = wxEmptyString, const wxString& message = "Select a folder", const wxPoint& pos = wxDefaultPosition, @@ -248,14 +231,14 @@ public: Just like SetPath() but this function takes a wxFileName object. */ - void SetDirName(const wxFileName & dirname); + void SetDirName(const wxFileName& dirname); /** Sets the absolute path of (the default converter uses current locale's charset)the currently selected directory. This must be a valid directory if @c wxDIRP_DIR_MUST_EXIST style was given. */ - void SetPath(const wxString & dirname); + void SetPath(const wxString& dirname); }; @@ -278,7 +261,7 @@ public: /** The constructor is not normally used by the user code. */ - wxFileDirPickerEvent(wxEventType type, wxObject * generator, + wxFileDirPickerEvent(wxEventType type, wxObject* generator, int id, const wxString path); @@ -290,5 +273,5 @@ public: /** Set the absolute path of the file/directory associated with the event. */ - void SetPath(const wxString & path); + void SetPath(const wxString& path); }; diff --git a/interface/filesys.h b/interface/filesys.h index 9831bf3cca..d56f823cd3 100644 --- a/interface/filesys.h +++ b/interface/filesys.h @@ -38,51 +38,47 @@ public: static void AddHandler(wxFileSystemHandler handler); /** - Sets the current location. @e location parameter passed to + Sets the current location. @a location parameter passed to OpenFile() is relative to this path. - - @b Caution! Unless @e is_dir is @true the @e location parameter + @b Caution! Unless @a is_dir is @true the @a location parameter is not the directory name but the name of the file in this directory. All these commands change the path to "dir/subdir/": @param location - the new location. Its meaning depends on the value of is_dir - + the new location. Its meaning depends on the value of is_dir @param is_dir - if @true location is new directory. If @false (default) - location is file in the new directory. + if @true location is new directory. If @false (default) + location is file in the new directory. */ - void ChangePathTo(const wxString& location, bool is_dir = @false); + void ChangePathTo(const wxString& location, bool is_dir = false); /** Converts filename into URL. - @sa URLToFileName(), wxFileName + @see URLToFileName(), wxFileName */ static wxString FileNameToURL(wxFileName filename); /** - Looks for the file with the given name @e file in a colon or semi-colon + Looks for the file with the given name @a file in a colon or semi-colon (depending on the current platform) separated list of directories in @e path. If the file is found in any directory, returns @true and the full path of the file in @e str, otherwise returns @false and doesn't modify @e str. @param str - Receives the full path of the file, must not be @NULL - + Receives the full path of the file, must not be @NULL @param path - wxPATH_SEP-separated list of directories - + wxPATH_SEP-separated list of directories @param file - the name of the file to look for + the name of the file to look for */ bool FindFileInPath(wxString str, const wxString& path, const wxString& file); /** Works like wxFindFirstFile. Returns name of the first - filename (within filesystem's current path) that matches @e wildcard. @e flags + filename (within filesystem's current path) that matches @e wildcard. @a flags may be one of wxFILE (only files), wxDIR (only directories) or 0 (both). */ @@ -103,7 +99,7 @@ public: open the given location. */ - static bool HasHandlerForPath(const wxString & location); + static bool HasHandlerForPath(const wxString& location); /** Opens the file and returns a pointer to a wxFSFile object @@ -111,11 +107,11 @@ public: (based on value passed to ChangePathTo() method) and then as an absolute path. Note that the user is responsible for deleting the returned wxFSFile. + @a flags can be one or more of the following bit values ored together: - @e flags can be one or more of the following bit values ored together: A stream opened with just the default @e wxFS_READ flag may or may not be seekable depending on the underlying source. - Passing @e wxFS_READ | wxFS_SEEKABLE for @e flags will + Passing @e wxFS_READ | wxFS_SEEKABLE for @a flags will back a stream that is not natively seekable with memory or a file and return a stream that is always seekable. */ @@ -157,18 +153,15 @@ public: Constructor. You probably won't use it. See Notes for details. @param stream - The input stream that will be used to access data - + The input stream that will be used to access data @param location - The full location (aka filename) of the file - + The full location (aka filename) of the file @param mimetype - MIME type of this file. It may be left empty, in which - case the type will be determined from file's extension (location must - not be empty in this case). - + MIME type of this file. It may be left empty, in which + case the type will be determined from file's extension (location must + not be empty in this case). @param anchor - Anchor. See GetAnchor() for details. + Anchor. See GetAnchor() for details. */ wxFSFile(wxInputStream stream, const wxString& loc, const wxString& mimetype, @@ -185,6 +178,7 @@ public: /** Returns anchor (if present). The term of @b anchor can be easily explained using few examples: + Usually an anchor is presented only if the MIME type is 'text/html'. But it may have some meaning with other files; for example myanim.avi#200 may refer to position in animation @@ -260,16 +254,16 @@ public: Returns @true if the handler is able to open this file. This function doesn't check whether the file exists or not, it only checks if it knows the protocol. Example: + Must be overridden in derived handlers. */ virtual bool CanOpen(const wxString& location); /** Works like wxFindFirstFile. Returns name of the first - filename (within filesystem's current path) that matches @e wildcard. @e flags + filename (within filesystem's current path) that matches @e wildcard. @a flags may be one of wxFILE (only files), wxDIR (only directories) or 0 (both). - This method is only called if CanOpen() returns @true. */ virtual wxString FindFirst(const wxString& wildcard, @@ -277,7 +271,6 @@ public: /** Returns next filename that matches parameters passed to wxFileSystem::FindFirst. - This method is only called if CanOpen() returns @true and FindFirst returned a non-empty string. */ @@ -286,16 +279,13 @@ public: /** Returns the anchor if present in the location. See @ref wxFSFile::getanchor wxFSFile for details. - Example: GetAnchor("index.htm#chapter2") == "chapter2" - @b Note: the anchor is NOT part of the left location. */ wxString GetAnchor(const wxString& location); /** Returns the left location string extracted from @e location. - Example: GetLeftLocation("file:myzipfile.zip#zip:index.htm") == "file:myzipfile.zip" */ @@ -305,36 +295,31 @@ public: Returns the MIME type based on @b extension of @e location. (While wxFSFile::GetMimeType returns real MIME type - either extension-based or queried from HTTP.) - Example : GetMimeTypeFromExt("index.htm") == "text/html" */ wxString GetMimeTypeFromExt(const wxString& location); /** Returns the protocol string extracted from @e location. - Example: GetProtocol("file:myzipfile.zip#zip:index.htm") == "zip" */ wxString GetProtocol(const wxString& location); /** Returns the right location string extracted from @e location. - Example : GetRightLocation("file:myzipfile.zip#zip:index.htm") == "index.htm" */ wxString GetRightLocation(const wxString& location); /** Opens the file and returns wxFSFile pointer or @NULL if failed. - Must be overridden in derived handlers. @param fs - Parent FS (the FS from that OpenFile was called). See ZIP handler - for details of how to use it. - + Parent FS (the FS from that OpenFile was called). See ZIP handler + for details of how to use it. @param location - The absolute location of file. + The absolute location of file. */ virtual wxFSFile* OpenFile(wxFileSystem& fs, const wxString& location); diff --git a/interface/font.h b/interface/font.h index 02020ace46..b2dd00387a 100644 --- a/interface/font.h +++ b/interface/font.h @@ -41,7 +41,7 @@ wxSWISS_FONT @seealso - @ref overview_wxfontoverview "wxFont overview", wxDC::SetFont, wxDC::DrawText, + @ref overview_wxfontoverview, wxDC::SetFont, wxDC::DrawText, wxDC::GetTextExtent, wxFontDialog, wxSystemSettings */ class wxFont : public wxGDIObject @@ -52,134 +52,226 @@ public: Creates a font object with the specified attributes. @param pointSize - Size in points. - + Size in points. @param pixelSize - Size in pixels: this is directly supported only under MSW - currently where this constructor can be used directly, under other platforms a - font with the closest size to the given one is found using binary search and - the static New method must be used. - + Size in pixels: this is directly supported only under MSW + currently where this constructor can be used directly, under other + platforms a + font with the closest size to the given one is found using binary search and + the static New method must be used. @param family - Font family, a generic way of referring to fonts without specifying actual + Font family, a generic way of referring to fonts without specifying actual facename. One of: - wxFONTFAMILY_DEFAULT - Chooses a default font. - wxFONTFAMILY_DECORATIVE - A decorative font. + wxFONTFAMILY_DEFAULT - wxFONTFAMILY_ROMAN - A formal, serif font. - wxFONTFAMILY_SCRIPT + Chooses a default font. - A handwriting font. - wxFONTFAMILY_SWISS - A sans-serif font. + wxFONTFAMILY_DECORATIVE - wxFONTFAMILY_MODERN - A fixed pitch font. - wxFONTFAMILY_TELETYPE + A decorative font. - A teletype font. - @param style - One of wxFONTSTYLE_NORMAL, wxFONTSTYLE_SLANT and wxFONTSTYLE_ITALIC. + + wxFONTFAMILY_ROMAN + + + + + A formal, serif font. + + + + + + wxFONTFAMILY_SCRIPT + + + + + A handwriting font. + + + + + + wxFONTFAMILY_SWISS + + + + + A sans-serif font. + + + + + + wxFONTFAMILY_MODERN + + + + + A fixed pitch font. + + + + + + wxFONTFAMILY_TELETYPE + + + + + A teletype font. + @param style + One of wxFONTSTYLE_NORMAL, wxFONTSTYLE_SLANT and wxFONTSTYLE_ITALIC. @param weight - Font weight, sometimes also referred to as font boldness. One of: + Font weight, sometimes also referred to as font boldness. One of: - wxFONTWEIGHT_NORMAL - Normal font. - wxFONTWEIGHT_LIGHT - Light font. + wxFONTWEIGHT_NORMAL - wxFONTWEIGHT_BOLD - Bold font. - @param underline - The value can be @true or @false. At present this has an effect on Windows and - Motif 2.x only. + Normal font. + + + + + + wxFONTWEIGHT_LIGHT + + - @param faceName - An optional string specifying the actual typeface to be used. If it is an empty - string, - a default typeface will be chosen based on the family. + Light font. + + + + + + wxFONTWEIGHT_BOLD + + + + + Bold font. + @param underline + The value can be @true or @false. At present this has an effect on Windows + and Motif 2.x only. + @param faceName + An optional string specifying the actual typeface to be used. If it is an + empty string, + a default typeface will be chosen based on the family. @param encoding - An encoding which may be one of + An encoding which may be one of + + + + + + + + wxFONTENCODING_SYSTEM + + + + + Default system encoding. + + + + + + wxFONTENCODING_DEFAULT + + + + + Default application encoding: this + is the encoding set by calls to + SetDefaultEncoding and which may be set to, + say, KOI8 to create all fonts by default with KOI8 encoding. Initially, the + default application encoding is the same as default system encoding. - wxFONTENCODING_SYSTEM - Default system encoding. - wxFONTENCODING_DEFAULT + wxFONTENCODING_ISO8859_1...15 - Default application encoding: this - is the encoding set by calls to - SetDefaultEncoding and which may be set to, - say, KOI8 to create all fonts by default with KOI8 encoding. Initially, the - default application encoding is the same as default system encoding. - wxFONTENCODING_ISO8859_1...15 - ISO8859 encodings. + ISO8859 encodings. - wxFONTENCODING_KOI8 - The standard Russian encoding for Internet. - wxFONTENCODING_CP1250...1252 + wxFONTENCODING_KOI8 - Windows encodings similar to ISO8859 (but not identical). - If the specified encoding isn't available, no font is created - (see also font encoding overview). + + + The standard Russian encoding for Internet. + + + + + + wxFONTENCODING_CP1250...1252 + + + + + Windows encodings similar to ISO8859 (but not identical). + + + + + + If the specified encoding isn't available, no font is created + (see also font encoding overview). @remarks If the desired font does not exist, the closest match will be - chosen. Under Windows, only scalable TrueType fonts - are used. + chosen. Under Windows, only scalable TrueType fonts are + used. */ wxFont(); wxFont(const wxFont& font); wxFont(int pointSize, wxFontFamily family, int style, wxFontWeight weight, - const bool underline = @false, + const bool underline = false, const wxString& faceName = "", wxFontEncoding encoding = wxFONTENCODING_DEFAULT); wxFont(const wxSize& pixelSize, wxFontFamily family, int style, wxFontWeight weight, - const bool underline = @false, + const bool underline = false, const wxString& faceName = "", wxFontEncoding encoding = wxFONTENCODING_DEFAULT); //@} @@ -190,19 +282,17 @@ public: more info. @remarks Although all remaining fonts are deleted when the application - exits, the application should try to clean up all - fonts itself. This is because wxWidgets cannot know - if a pointer to the font object is stored in an - application data structure, and there is a risk of - double deletion. + exits, the application should try to clean up all fonts + itself. This is because wxWidgets cannot know if a + pointer to the font object is stored in an application + data structure, and there is a risk of double deletion. */ ~wxFont(); /** Returns the current application's default encoding. - @sa @ref overview_wxfontencodingoverview "Font encoding overview", - SetDefaultEncoding() + @see @ref overview_wxfontencodingoverview, SetDefaultEncoding() */ static wxFontEncoding GetDefaultEncoding(); @@ -211,7 +301,7 @@ public: there is no typeface information. - @sa SetFaceName() + @see SetFaceName() */ wxString GetFaceName(); @@ -219,7 +309,7 @@ public: Gets the font family. See SetFamily() for a list of valid family identifiers. - @sa SetFamily() + @see SetFamily() */ wxFontFamily GetFamily(); @@ -230,7 +320,7 @@ public: typical use of this function is for serializing in string-form a wxFont object. - @sa SetNativeFontInfo(),GetNativeFontInfoUserDesc() + @see SetNativeFontInfo(),GetNativeFontInfoUserDesc() */ wxString GetNativeFontInfoDesc(); @@ -240,14 +330,14 @@ public: Some examples of the formats of returned strings (which are platform-dependent) are in SetNativeFontInfoUserDesc(). - @sa GetNativeFontInfoDesc() + @see GetNativeFontInfoDesc() */ wxString GetNativeFontInfoUserDesc(); /** Gets the point size. - @sa SetPointSize() + @see SetPointSize() */ int GetPointSize(); @@ -255,14 +345,14 @@ public: Gets the font style. See wxFont() for a list of valid styles. - @sa SetStyle() + @see SetStyle() */ int GetStyle(); /** Returns @true if the font is underlined, @false otherwise. - @sa SetUnderlined() + @see SetUnderlined() */ bool GetUnderlined(); @@ -270,7 +360,7 @@ public: Gets the font weight. See wxFont() for a list of valid weight identifiers. - @sa SetWeight() + @see SetWeight() */ wxFontWeight GetWeight(); @@ -283,45 +373,42 @@ public: /** Returns @true if this object is a valid font, @false otherwise. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); //@{ /** These functions take the same parameters as @ref ctor() wxFont constructor and return a new font object allocated on the heap. - Using @c New() is currently the only way to directly create a font with the given size in pixels on platforms other than wxMSW. */ - static wxFont * New(int pointSize, wxFontFamily family, - int style, - wxFontWeight weight, - const bool underline = @false, - const wxString& faceName = "", - wxFontEncoding encoding = wxFONTENCODING_DEFAULT); - static wxFont * New(int pointSize, wxFontFamily family, - int flags = wxFONTFLAG_DEFAULT, - const wxString& faceName = "", - wxFontEncoding encoding = wxFONTENCODING_DEFAULT); - static wxFont * New(const wxSize& pixelSize, - wxFontFamily family, - int style, - wxFontWeight weight, - const bool underline = @false, - const wxString& faceName = "", - wxFontEncoding encoding = wxFONTENCODING_DEFAULT); - static wxFont * New(const wxSize& pixelSize, - wxFontFamily family, - int flags = wxFONTFLAG_DEFAULT, - const wxString& faceName = "", - wxFontEncoding encoding = wxFONTENCODING_DEFAULT); + static wxFont* New(int pointSize, wxFontFamily family, int style, + wxFontWeight weight, + const bool underline = false, + const wxString& faceName = "", + wxFontEncoding encoding = wxFONTENCODING_DEFAULT); + static wxFont* New(int pointSize, wxFontFamily family, + int flags = wxFONTFLAG_DEFAULT, + const wxString& faceName = "", + wxFontEncoding encoding = wxFONTENCODING_DEFAULT); + static wxFont* New(const wxSize& pixelSize, + wxFontFamily family, + int style, + wxFontWeight weight, + const bool underline = false, + const wxString& faceName = "", + wxFontEncoding encoding = wxFONTENCODING_DEFAULT); + static wxFont* New(const wxSize& pixelSize, + wxFontFamily family, + int flags = wxFONTFLAG_DEFAULT, + const wxString& faceName = "", + wxFontEncoding encoding = wxFONTENCODING_DEFAULT); //@} /** Sets the default font encoding. - @sa @ref overview_wxfontencodingoverview "Font encoding overview", - GetDefaultEncoding() + @see @ref overview_wxfontencodingoverview, GetDefaultEncoding() */ static void SetDefaultEncoding(wxFontEncoding encoding); @@ -330,16 +417,16 @@ public: Returns @true if the given face name exists; @false otherwise. @param faceName - A valid facename, which should be on the end-user's system. + A valid facename, which should be on the end-user's system. @remarks To avoid portability problems, don't rely on a specific face, - but specify the font family instead or as well. A - suitable font will be found on the end-user's system. - If both the family and the facename are specified, - wxWidgets will first search for the specific face, - and then for a font belonging to the same family. + but specify the font family instead or as well. A + suitable font will be found on the end-user's system. + If both the family and the facename are specified, + wxWidgets will first search for the specific face, and + then for a font belonging to the same family. - @sa GetFaceName(), SetFamily() + @see GetFaceName(), SetFamily() */ bool SetFaceName(const wxString& faceName); @@ -347,45 +434,88 @@ public: Sets the font family. @param family - One of: + One of: + + + + + + + + wxFONTFAMILY_DEFAULT + + + + + Chooses a default font. + + + + + + wxFONTFAMILY_DECORATIVE + + + + + A decorative font. + + + + + + wxFONTFAMILY_ROMAN - wxFONTFAMILY_DEFAULT - Chooses a default font. + A formal, serif font. - wxFONTFAMILY_DECORATIVE - A decorative font. - wxFONTFAMILY_ROMAN + wxFONTFAMILY_SCRIPT - A formal, serif font. - wxFONTFAMILY_SCRIPT - A handwriting font. + A handwriting font. - wxFONTFAMILY_SWISS - A sans-serif font. - wxFONTFAMILY_MODERN + wxFONTFAMILY_SWISS - A fixed pitch font. - wxFONTFAMILY_TELETYPE - A teletype font. + A sans-serif font. - @sa GetFamily(), SetFaceName() + + + + + wxFONTFAMILY_MODERN + + + + + A fixed pitch font. + + + + + + wxFONTFAMILY_TELETYPE + + + + + A teletype font. + + @see GetFamily(), SetFaceName() */ void SetFamily(wxFontFamily family); @@ -399,7 +529,7 @@ public: a wxFont object previously saved in a string-form. - @sa SetNativeFontInfoUserDesc() + @see SetNativeFontInfoUserDesc() */ bool SetNativeFontInfo(const wxString& info); @@ -411,31 +541,26 @@ public: strings which are user-friendly. Examples of accepted string formats are: - Generic syntax - Example on @b wxGTK2: @c [FACE-NAME] [bold] [oblique|italic] [POINTSIZE] - Monospace bold 10 on @b wxMSW: @c [light|bold] [italic] [FACE-NAME] [POINTSIZE] [ENCODING] - Tahoma 10 WINDOWS-1252 on @b wxMac: FIXME - FIXME For more detailed information about the allowed syntaxes you can look at the documentation of the native API used for font-rendering (e.g. pango_font_description_from_string). - @sa SetNativeFontInfo() + @see SetNativeFontInfo() */ bool SetNativeFontInfoUserDesc(const wxString& info); @@ -443,9 +568,9 @@ public: Sets the point size. @param pointSize - Size in points. + Size in points. - @sa GetPointSize() + @see GetPointSize() */ void SetPointSize(int pointSize); @@ -453,9 +578,9 @@ public: Sets the font style. @param style - One of wxFONTSTYLE_NORMAL, wxFONTSTYLE_SLANT and wxFONTSTYLE_ITALIC. + One of wxFONTSTYLE_NORMAL, wxFONTSTYLE_SLANT and wxFONTSTYLE_ITALIC. - @sa GetStyle() + @see GetStyle() */ void SetStyle(int style); @@ -463,9 +588,9 @@ public: Sets underlining. @param underlining - @true to underline, @false otherwise. + @true to underline, @false otherwise. - @sa GetUnderlined() + @see GetUnderlined() */ void SetUnderlined(const bool underlined); @@ -473,25 +598,44 @@ public: Sets the font weight. @param weight - One of: + One of: + + + + + + + + wxFONTWEIGHT_NORMAL + + + + + Normal font. + + + + + + wxFONTWEIGHT_LIGHT + + + + Light font. - wxFONTWEIGHT_NORMAL - Normal font. - wxFONTWEIGHT_LIGHT + wxFONTWEIGHT_BOLD - Light font. - wxFONTWEIGHT_BOLD - Bold font. + Bold font. - @sa GetWeight() + @see GetWeight() */ void SetWeight(wxFontWeight weight); diff --git a/interface/fontdlg.h b/interface/fontdlg.h index 6967642dd3..fc253cca55 100644 --- a/interface/fontdlg.h +++ b/interface/fontdlg.h @@ -56,7 +56,6 @@ public: /** Shows the dialog, returning @c wxID_OK if the user pressed Ok, and @c wxID_CANCEL otherwise. - If the user cancels the dialog (ShowModal returns @c wxID_CANCEL), no font will be created. If the user presses OK, a new wxFont will be created and stored in the font dialog's wxFontData structure. @@ -75,15 +74,13 @@ public: is valid) if the dialog was cancelled. @param parent - The parent window for the font selection dialog - + The parent window for the font selection dialog @param fontInit - If given, this will be the font initially selected in the dialog. - + If given, this will be the font initially selected in the dialog. @param caption - If given, this will be used for the dialog caption. + If given, this will be used for the dialog caption. */ -wxFont wxGetFontFromUser(wxWindow * parent, +wxFont wxGetFontFromUser(wxWindow* parent, const wxFont& fontInit, const wxString& caption = wxEmptyString); diff --git a/interface/fontenum.h b/interface/fontenum.h index 1ab4b739d4..400cefc14a 100644 --- a/interface/fontenum.h +++ b/interface/fontenum.h @@ -27,8 +27,8 @@ @category{FIXME} @seealso - @ref overview_wxfontencodingoverview "Font encoding overview", @ref - overview_samplefont "Font sample", wxFont, wxFontMapper + @ref overview_wxfontencodingoverview, @ref overview_samplefont "Font sample", + wxFont, wxFontMapper */ class wxFontEnumerator { @@ -36,20 +36,19 @@ public: /** Call OnFontEncoding() for each encoding supported by the given font - or for each encoding supported by at - least some font if @e font is not specified. + least some font if @a font is not specified. */ virtual bool EnumerateEncodings(const wxString& font = ""); /** Call OnFacename() for each font which supports given encoding (only if it is not wxFONTENCODING_SYSTEM) and is of - fixed width (if @e fixedWidthOnly is @true). - + fixed width (if @a fixedWidthOnly is @true). Calling this function with default arguments will result in enumerating all fonts available on the system. */ virtual bool EnumerateFacenames(wxFontEncoding encoding = wxFONTENCODING_SYSTEM, - bool fixedWidthOnly = @false); + bool fixedWidthOnly = false); /** Return array of strings containing all encodings found by @@ -62,14 +61,14 @@ public: EnumerateFacenames(). */ static wxArrayString GetFacenames(wxFontEncoding encoding = wxFONTENCODING_SYSTEM, - bool fixedWidthOnly = @false); + bool fixedWidthOnly = false); /** Returns @true if the given string is valid face name, i.e. it's the face name of an installed font and it can safely be used with wxFont::SetFaceName. */ - static bool IsValidFacename(const wxString & facename); + static bool IsValidFacename(const wxString& facename); /** Called by EnumerateFacenames() for diff --git a/interface/fontmap.h b/interface/fontmap.h index 719c3f14a8..f3591f369f 100644 --- a/interface/fontmap.h +++ b/interface/fontmap.h @@ -51,8 +51,7 @@ public: /** Returns the encoding for the given charset (in the form of RFC 2046) or @c wxFONTENCODING_SYSTEM if couldn't decode it. - - Be careful when using this function with @e interactive set to @true + Be careful when using this function with @a interactive set to @true (default value) as the function then may show a dialog box to the user which may lead to unexpected reentrancies and may also take a significantly longer time than a simple function call. For these reasons, it is almost always a bad @@ -60,15 +59,15 @@ public: events such as @c EVT_PAINT. */ wxFontEncoding CharsetToEncoding(const wxString& charset, - bool interactive = @true); + bool interactive = true); /** Get the current font mapper object. If there is no current object, creates one. - @sa Set() + @see Set() */ -#define static wxFontMapper * Get() /* implementation is private */ + static wxFontMapper* Get(); /** Returns the array of all possible names for the given encoding. The array is @@ -84,7 +83,6 @@ public: available on this system). If successful, return @true and fill info structure with the parameters required to create the font, otherwise return @false. - The first form is for wxWidgets' internal use while the second one is better suitable for general use -- it returns wxFontEncoding which can consequently be passed to wxFont constructor. @@ -92,11 +90,11 @@ public: bool GetAltForEncoding(wxFontEncoding encoding, wxNativeEncodingInfo* info, const wxString& facename = wxEmptyString, - bool interactive = @true); + bool interactive = true); bool GetAltForEncoding(wxFontEncoding encoding, wxFontEncoding* alt_encoding, const wxString& facename = wxEmptyString, - bool interactive = @true); + bool interactive = true); //@} /** @@ -126,7 +124,7 @@ public: Return internal string identifier for the encoding (see also wxFontMapper::GetEncodingDescription) - @sa GetEncodingFromName() + @see GetEncodingFromName() */ static wxString GetEncodingName(wxFontEncoding encoding); @@ -149,13 +147,12 @@ public: This method is only useful if you want to plug-in an alternative font mapper into wxWidgets. - @sa Get() + @see Get() */ -#define static wxFontMapper * Set(wxFontMapper * mapper) /* implementation is private */ + static wxFontMapper* Set(wxFontMapper* mapper); /** Set the config object to use (may be @NULL to use default). - By default, the global one (from wxConfigBase::Get() will be used) and the default root path for the config settings is the string returned by GetDefaultConfigPath(). diff --git a/interface/fontpicker.h b/interface/fontpicker.h index c782ba92f9..3f278aad57 100644 --- a/interface/fontpicker.h +++ b/interface/fontpicker.h @@ -50,7 +50,7 @@ public: Initializes the object and calls Create() with all the parameters. */ - wxFontPickerCtrl(wxWindow * parent, wxWindowID id, + wxFontPickerCtrl(wxWindow* parent, wxWindowID id, const wxFont& font = wxNullFont, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, @@ -60,34 +60,27 @@ public: /** @param parent - Parent window, must not be non-@NULL. - + Parent window, must not be non-@NULL. @param id - The identifier for the control. - + The identifier for the control. @param font - The initial font shown in the control. If wxNullFont - is given, the default font is used. - + The initial font shown in the control. If wxNullFont + is given, the default font is used. @param pos - Initial position. - + Initial position. @param size - Initial size. - + Initial size. @param style - The window style, see wxFNTP_* flags. - + The window style, see wxFNTP_* flags. @param validator - Validator which can be used for additional date checks. - + Validator which can be used for additional date checks. @param name - Control name. + Control name. @returns @true if the control was successfully created or @false if - creation failed. + creation failed. */ - bool Create(wxWindow * parent, wxWindowID id, + bool Create(wxWindow* parent, wxWindowID id, const wxFont& font = wxNullFont, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, @@ -122,7 +115,7 @@ public: Sets the currently selected font. Note that this function is completely different from wxWindow::SetFont. */ - void SetSelectedFont(const wxFont & font); + void SetSelectedFont(const wxFont& font); }; @@ -145,7 +138,7 @@ public: /** The constructor is not normally used by the user code. */ - wxFontPickerEvent(wxObject * generator, int id, + wxFontPickerEvent(wxObject* generator, int id, const wxFont& font); /** @@ -156,5 +149,5 @@ public: /** Set the font associated with the event. */ - void SetFont(const wxFont & f); + void SetFont(const wxFont& f); }; diff --git a/interface/frame.h b/interface/frame.h index 578cc889e5..1ade0d6b38 100644 --- a/interface/frame.h +++ b/interface/frame.h @@ -93,37 +93,33 @@ public: Constructor, creating the window. @param parent - The window parent. This may be @NULL. If it is non-@NULL, the frame will - always be displayed on top of the parent window on Windows. - + The window parent. This may be @NULL. If it is non-@NULL, the frame will + always be displayed on top of the parent window on Windows. @param id - The window identifier. It may take a value of -1 to indicate a default value. - + The window identifier. It may take a value of -1 to indicate a default + value. @param title - The caption to be displayed on the frame's title bar. - + The caption to be displayed on the frame's title bar. @param pos - The window position. The value wxDefaultPosition indicates a default position, chosen by - either the windowing system or wxWidgets, depending on platform. - + The window position. The value wxDefaultPosition indicates a default position, + chosen by + either the windowing system or wxWidgets, depending on platform. @param size - The window size. The value wxDefaultSize indicates a default size, chosen by - either the windowing system or wxWidgets, depending on platform. - + The window size. The value wxDefaultSize indicates a default size, chosen by + either the windowing system or wxWidgets, depending on platform. @param style - The window style. See wxFrame. - + The window style. See wxFrame. @param name - The name of the window. This parameter is used to associate a name with the + The name of the window. This parameter is used to associate a name with the item, - allowing the application user to set Motif resource values for - individual windows. + allowing the application user to set Motif resource values for + individual windows. @remarks For Motif, MWM (the Motif Window Manager) should be running for - any window styles to work (otherwise all styles take - effect). + any window styles to work (otherwise all styles take + effect). - @sa Create() + @see Create() */ wxFrame(); wxFrame(wxWindow* parent, wxWindowID id, @@ -143,7 +139,7 @@ public: Centres the frame on the display. @param direction - The parameter may be wxHORIZONTAL, wxVERTICAL or wxBOTH. + The parameter may be wxHORIZONTAL, wxVERTICAL or wxBOTH. */ void Centre(int direction = wxBOTH); @@ -162,29 +158,25 @@ public: Creates a status bar at the bottom of the frame. @param number - The number of fields to create. Specify a - value greater than 1 to create a multi-field status bar. - + The number of fields to create. Specify a + value greater than 1 to create a multi-field status bar. @param style - The status bar style. See wxStatusBar for a list - of valid styles. - + The status bar style. See wxStatusBar for a list + of valid styles. @param id - The status bar window identifier. If -1, an identifier will be chosen by - wxWidgets. - + The status bar window identifier. If -1, an identifier will be chosen by + wxWidgets. @param name - The status bar window name. + The status bar window name. @returns A pointer to the status bar if it was created successfully, @NULL - otherwise. + otherwise. @remarks The width of the status bar is the whole width of the frame - (adjusted automatically when resizing), and the - height and text size are chosen by the host windowing - system. + (adjusted automatically when resizing), and the height + and text size are chosen by the host windowing system. - @sa SetStatusText(), OnCreateStatusBar(), GetStatusBar() + @see SetStatusText(), OnCreateStatusBar(), GetStatusBar() */ virtual wxStatusBar* CreateStatusBar(int number = 1, long style = 0, @@ -195,28 +187,26 @@ public: Creates a toolbar at the top or left of the frame. @param style - The toolbar style. See wxToolBar for a list - of valid styles. - + The toolbar style. See wxToolBar for a list + of valid styles. @param id - The toolbar window identifier. If -1, an identifier will be chosen by - wxWidgets. - + The toolbar window identifier. If -1, an identifier will be chosen by + wxWidgets. @param name - The toolbar window name. + The toolbar window name. @returns A pointer to the toolbar if it was created successfully, @NULL - otherwise. + otherwise. @remarks By default, the toolbar is an instance of wxToolBar (which is - defined to be a suitable toolbar class on each - platform, such as wxToolBar95). To use a different - class, override OnCreateToolBar(). + defined to be a suitable toolbar class on each + platform, such as wxToolBar95). To use a different + class, override OnCreateToolBar(). - @sa CreateStatusBar(), OnCreateToolBar(), SetToolBar(), - GetToolBar() + @see CreateStatusBar(), OnCreateToolBar(), SetToolBar(), + GetToolBar() */ - virtual wxToolBar* CreateToolBar(long style = wxBORDER_NONE | wxTB_HORIZONTAL, + virtual wxToolBar* CreateToolBar(long style = wxBORDER_NONE | wxTB_HORIZONTAL, wxWindowID id = -1, const wxString& name = "toolBar"); @@ -229,7 +219,7 @@ public: /** Returns a pointer to the menubar currently associated with the frame (if any). - @sa SetMenuBar(), wxMenuBar, wxMenu + @see SetMenuBar(), wxMenuBar, wxMenu */ wxMenuBar* GetMenuBar(); @@ -237,21 +227,21 @@ public: Returns a pointer to the status bar currently associated with the frame (if any). - @sa CreateStatusBar(), wxStatusBar + @see CreateStatusBar(), wxStatusBar */ wxStatusBar* GetStatusBar(); /** Returns the status bar pane used to display menu and toolbar help. - @sa SetStatusBarPane() + @see SetStatusBarPane() */ int GetStatusBarPane(); /** Returns a pointer to the toolbar currently associated with the frame (if any). - @sa CreateToolBar(), wxToolBar, SetToolBar() + @see CreateToolBar(), wxToolBar, SetToolBar() */ wxToolBar* GetToolBar(); @@ -259,26 +249,23 @@ public: Virtual function called when a status bar is requested by CreateStatusBar(). @param number - The number of fields to create. - + The number of fields to create. @param style - The window style. See wxStatusBar for a list - of valid styles. - + The window style. See wxStatusBar for a list + of valid styles. @param id - The window identifier. If -1, an identifier will be chosen by - wxWidgets. - + The window identifier. If -1, an identifier will be chosen by + wxWidgets. @param name - The window name. + The window name. @returns A status bar object. @remarks An application can override this function to return a different - kind of status bar. The default implementation - returns an instance of wxStatusBar. + kind of status bar. The default implementation returns + an instance of wxStatusBar. - @sa CreateStatusBar(), wxStatusBar. + @see CreateStatusBar(), wxStatusBar. */ virtual wxStatusBar* OnCreateStatusBar(int number, long style, wxWindowID id, @@ -288,23 +275,21 @@ public: Virtual function called when a toolbar is requested by CreateToolBar(). @param style - The toolbar style. See wxToolBar for a list - of valid styles. - + The toolbar style. See wxToolBar for a list + of valid styles. @param id - The toolbar window identifier. If -1, an identifier will be chosen by - wxWidgets. - + The toolbar window identifier. If -1, an identifier will be chosen by + wxWidgets. @param name - The toolbar window name. + The toolbar window name. @returns A toolbar object. @remarks An application can override this function to return a different - kind of toolbar. The default implementation returns - an instance of wxToolBar. + kind of toolbar. The default implementation returns an + instance of wxToolBar. - @sa CreateToolBar(), wxToolBar. + @see CreateToolBar(), wxToolBar. */ virtual wxToolBar* OnCreateToolBar(long style, wxWindowID id, const wxString& name); @@ -313,7 +298,7 @@ public: Simulate a menu command. @param id - The identifier for a menu item. + The identifier for a menu item. */ void ProcessCommand(int id); @@ -322,7 +307,6 @@ public: forcing it to reevaluate its children positions. It is sometimes useful to call this function after adding or deleting a children after the frame creation or if a child size changes. - Note that if the frame is using either sizers or constraints for the children layout, it is enough to call wxWindow::Layout directly and this function should not be used in this case. @@ -333,21 +317,21 @@ public: Tells the frame to show the given menu bar. @param menuBar - The menu bar to associate with the frame. + The menu bar to associate with the frame. @remarks If the frame is destroyed, the menu bar and its menus will be - destroyed also, so do not delete the menu bar - explicitly (except by resetting the frame's menu bar - to another frame or @NULL). + destroyed also, so do not delete the menu bar + explicitly (except by resetting the frame's menu bar to + another frame or @NULL). - @sa GetMenuBar(), wxMenuBar, wxMenu. + @see GetMenuBar(), wxMenuBar, wxMenu. */ void SetMenuBar(wxMenuBar* menuBar); /** Associates a status bar with the frame. - @sa CreateStatusBar(), wxStatusBar, GetStatusBar() + @see CreateStatusBar(), wxStatusBar, GetStatusBar() */ void SetStatusBar(wxStatusBar* statusBar); @@ -361,14 +345,13 @@ public: Sets the status bar text and redraws the status bar. @param text - The text for the status field. - + The text for the status field. @param number - The status field (starting from zero). + The status field (starting from zero). @remarks Use an empty string to clear the status bar. - @sa CreateStatusBar(), wxStatusBar + @see CreateStatusBar(), wxStatusBar */ virtual void SetStatusText(const wxString& text, int number = 0); @@ -376,21 +359,21 @@ public: Sets the widths of the fields in the status bar. @param n - The number of fields in the status bar. It must be the - same used in CreateStatusBar. - + The number of fields in the status bar. It must be the + same used in CreateStatusBar. @param widths - Must contain an array of n integers, each of which is a status field width - in pixels. A value of -1 indicates that the field is variable width; at least - one - field must be -1. You should delete this array after calling SetStatusWidths. + Must contain an array of n integers, each of which is a status field width + in pixels. A value of -1 indicates that the field is variable width; at + least one + field must be -1. You should delete this array after calling + SetStatusWidths. @remarks The widths of the variable fields are calculated from the total - width of all fields, minus the sum of widths of the - non-variable fields, divided by the number of - variable fields. + width of all fields, minus the sum of widths of the + non-variable fields, divided by the number of variable + fields. */ - virtual void SetStatusWidths(int n, int * widths); + virtual void SetStatusWidths(int n, int* widths); /** Associates a toolbar with the frame. diff --git a/interface/fs_mem.h b/interface/fs_mem.h index ab950988b9..7c33133036 100644 --- a/interface/fs_mem.h +++ b/interface/fs_mem.h @@ -78,13 +78,12 @@ public: data (bitmap, text or raw data) will be copied into private memory stream and available under name "memory:" + @e filename. - - The @e type argument is one of @c wxBITMAP_TYPE_XXX constants. - Note that you must use a @e type value (aka image format) + The @a type argument is one of @c wxBITMAP_TYPE_XXX constants. + Note that you must use a @a type value (aka image format) that wxWidgets can save (e.g. JPG, PNG, see wxImage documentation)! - @sa AddFileWithMimeType() + @see AddFileWithMimeType() */ static void AddFile(const wxString& filename, wxImage& image, long type); @@ -98,10 +97,9 @@ public: Like AddFile(), but lets you explicitly specify added file's MIME type. This version should be used whenever you know the MIME type, because it makes accessing the files faster. - This function is new since wxWidgets version 2.8.5 - @sa AddFile() + @see AddFile() */ static void AddFileWithMimeType(const wxString& filename, const wxString& textdata, diff --git a/interface/gauge.h b/interface/gauge.h index 27df9b9fee..b9a3fd1cb4 100644 --- a/interface/gauge.h +++ b/interface/gauge.h @@ -51,28 +51,22 @@ public: Constructor, creating and showing a gauge. @param parent - Window parent. - + Window parent. @param id - Window identifier. - + Window identifier. @param range - Integer range (maximum value) of the gauge. It is ignored when the gauge is + Integer range (maximum value) of the gauge. It is ignored when the gauge is used in indeterminate mode. - @param pos - Window position. - + Window position. @param size - Window size. - + Window size. @param style - Gauge style. See wxGauge. - + Gauge style. See wxGauge. @param name - Window name. + Window name. - @sa Create() + @see Create() */ wxGauge(); wxGauge(wxWindow* parent, wxWindowID id, int range, @@ -104,14 +98,14 @@ public: @remarks This method is not implemented (returns 0) for most platforms. - @sa SetBezelFace() + @see SetBezelFace() */ int GetBezelFace(); /** Returns the maximum position of the gauge. - @sa SetRange() + @see SetRange() */ int GetRange(); @@ -120,14 +114,14 @@ public: @remarks This method is not implemented (returns 0) for most platforms. - @sa SetShadowWidth() + @see SetShadowWidth() */ int GetShadowWidth(); /** Returns the current position of the gauge. - @sa SetValue() + @see SetValue() */ int GetValue(); @@ -140,7 +134,6 @@ public: /** Switch the gauge to indeterminate mode (if required) and makes the gauge move a bit to indicate the user that some progress has been made. - Note that after calling this function the value returned by GetValue() is undefined and thus you need to explicitely call SetValue() if you want to restore the determinate mode. @@ -151,9 +144,9 @@ public: Sets the 3D bezel face width. @remarks This method is not implemented (doesn't do anything) for most - platforms. + platforms. - @sa GetBezelFace() + @see GetBezelFace() */ void SetBezelFace(int width); @@ -161,7 +154,7 @@ public: Sets the range (maximum value) of the gauge. This function makes the gauge switch to determinate mode, if it's not already. - @sa GetRange() + @see GetRange() */ void SetRange(int range); @@ -169,21 +162,20 @@ public: Sets the 3D shadow width. @remarks This method is not implemented (doesn't do anything) for most - platforms. + platforms. */ void SetShadowWidth(int width); /** - Sets the position of the gauge. The @e pos must be between 0 and the gauge + Sets the position of the gauge. The @a pos must be between 0 and the gauge range as returned by GetRange(), inclusive. - This function makes the gauge switch to determinate mode, if it was in indeterminate mode before. @param pos - Position for the gauge level. + Position for the gauge level. - @sa GetValue() + @see GetValue() */ void SetValue(int pos); }; diff --git a/interface/gbsizer.h b/interface/gbsizer.h index bbf1007449..7c41951596 100644 --- a/interface/gbsizer.h +++ b/interface/gbsizer.h @@ -92,18 +92,18 @@ public: const wxGBSpan& span = wxDefaultSpan, int flag = 0, int border = 0, - wxObject* userData = @NULL); + wxObject* userData = NULL); wxSizerItem* Add(wxSizer* sizer, const wxGBPosition& pos, const wxGBSpan& span = wxDefaultSpan, int flag = 0, int border = 0, - wxObject* userData = @NULL); + wxObject* userData = NULL); wxSizerItem* Add(int width, int height, const wxGBPosition& pos, const wxGBSpan& span = wxDefaultSpan, int flag = 0, int border = 0, - wxObject* userData = @NULL); + wxObject* userData = NULL); wxSizerItem* Add(wxGBSizerItem* item); //@} @@ -121,10 +121,10 @@ public: example it may be the item we are checking the position of. */ bool CheckForIntersection(wxGBSizerItem* item, - wxGBSizerItem* excludeItem = @NULL); + wxGBSizerItem* excludeItem = NULL); bool CheckForIntersection(const wxGBPosition& pos, const wxGBSpan& span, - wxGBSizerItem* excludeItem = @NULL); + wxGBSizerItem* excludeItem = NULL); //@} //@{ diff --git a/interface/gdicmn.h b/interface/gdicmn.h index f372fd5aa0..3c7c4832af 100644 --- a/interface/gdicmn.h +++ b/interface/gdicmn.h @@ -26,11 +26,8 @@ public: //@{ /** Create a point. - double x - double y - Members of the @b wxRealPoint object. */ wxRealPoint(); @@ -69,7 +66,7 @@ public: /** Returns the rectangle having the same size as this one but centered relatively to the given rectangle @e r. By default, rectangle is centred in both - directions but if @e dir includes only @c wxVERTICAL or only + directions but if @a dir includes only @c wxVERTICAL or only @c wxHORIZONTAL flag, then it is only centered in this direction while the other component of its position remains unchanged. */ @@ -90,12 +87,11 @@ public: //@{ /** Decrease the rectangle size. - This method is the opposite from Inflate(): Deflate(a, b) is equivalent to Inflate(-a, -b). Please refer to Inflate() for full description. - @sa Inflate() + @see Inflate() */ void Deflate(wxCoord dx, wxCoord dy); void Deflate(const wxSize& diff); @@ -141,7 +137,7 @@ public: /** Gets the size. - @sa SetSize() + @see SetSize() */ wxSize GetSize(); @@ -169,38 +165,32 @@ public: /** Gets the x member. */ -#define int GetX() /* implementation is private */ + int GetX(); /** Gets the y member. */ -#define int GetY() /* implementation is private */ + int GetY(); //@{ /** Increases the size of the rectangle. - - The second form uses the same @e diff for both @e dx and @e dy. - + The second form uses the same @a diff for both @a dx and @e dy. The first two versions modify the rectangle in place, the last one returns a new rectangle leaving this one unchanged. - The left border is moved farther left and the right border is moved farther right by @e dx. The upper border is moved farther up and the bottom border is moved farther down by @e dy. (Note the the width and height of the - rectangle thus change by 2*@e dx and 2*@e dy, respectively.) If one or - both of @e dx and @e dy are negative, the opposite happens: the rectangle + rectangle thus change by 2*@a dx and 2*@e dy, respectively.) If one or + both of @a dx and @a dy are negative, the opposite happens: the rectangle size decreases in the respective direction. - Inflating and deflating behaves "naturally''. Defined more precisely, that means: - - "Real'' inflates (that is, @e dx and/or @e dy = 0) are not + "Real'' inflates (that is, @a dx and/or @a dy = 0) are not constrained. Thus inflating a rectangle can cause its upper left corner to move into the negative numbers. (the versions prior to 2.5.4 forced the top left coordinate to not fall below (0, 0), which implied a forced move of the rectangle.) - Deflates are clamped to not reduce the width or height of the rectangle below zero. In such cases, the top-left corner is nonetheless handled properly. For example, a rectangle at (10, 10) with size (20, @@ -210,7 +200,7 @@ public: whereas the height is reduced by the full 30 (rather than also stopping at 20, when the width reached zero). - @sa Deflate() + @see Deflate() */ void Inflate(wxCoord dx, wxCoord dy); void Inflate(const wxSize& diff); @@ -230,7 +220,7 @@ public: /** Returns @true if this rectangle has a non-empty intersection with the - rectangle @e rect and @false otherwise. + rectangle @a rect and @false otherwise. */ bool Intersects(const wxRect& rect); @@ -242,8 +232,8 @@ public: //@{ /** - Moves the rectangle by the specified offset. If @e dx is positive, the - rectangle is moved to the right, if @e dy is positive, it is moved to the + Moves the rectangle by the specified offset. If @a dx is positive, the + rectangle is moved to the right, if @a dy is positive, it is moved to the bottom, otherwise it is moved to the left or top respectively. */ void Offset(wxCoord dx, wxCoord dy); @@ -258,7 +248,7 @@ public: /** Sets the size. - @sa GetSize() + @see GetSize() */ void SetSize(const wxSize& s); @@ -270,12 +260,12 @@ public: /** Sets the x position. */ -#define void SetX(int x) /* implementation is private */ + void SetX(int x); /** Sets the y position. */ -#define void SetY(int y) /* implementation is private */ + void SetY(int y); //@{ /** @@ -289,7 +279,6 @@ public: /** int height - Height member. */ @@ -318,21 +307,18 @@ public: /** int width - Width member. */ /** int x - x coordinate of the top-level corner of the rectangle. */ /** int y - y coordinate of the top-level corner of the rectangle. */ }; @@ -365,13 +351,12 @@ public: to the brush list, and returns it. @param colour - Colour object. - + Colour object. @param style - Brush style. See wxBrush::SetStyle for a list of styles. + Brush style. See wxBrush::SetStyle for a list of styles. */ - wxBrush * FindOrCreateBrush(const wxColour& colour, - int style = wxSOLID); + wxBrush* FindOrCreateBrush(const wxColour& colour, + int style = wxSOLID); }; @@ -423,14 +408,12 @@ public: /** int x - x member. */ /** int y - y member. */ }; @@ -468,7 +451,6 @@ public: /** Adds a colour to the database. If a colour with the same name already exists, it is replaced. - Please note that the overload taking a pointer is deprecated and will be removed in the next wxWidgets version, please don't use it. */ @@ -526,11 +508,11 @@ public: list. See the @ref wxFont::ctor "wxFont constructor" for details of the arguments. */ - wxFont * FindOrCreateFont(int point_size, int family, int style, - int weight, - bool underline = @false, - const wxString& facename = @NULL, - wxFontEncoding encoding = wxFONTENCODING_DEFAULT); + wxFont* FindOrCreateFont(int point_size, int family, int style, + int weight, + bool underline = false, + const wxString& facename = NULL, + wxFontEncoding encoding = wxFONTENCODING_DEFAULT); }; @@ -570,12 +552,11 @@ public: //@{ /** Decreases the size in x- and y- directions - By @e size.x and @e size.y for the first overload - By @e dx and @e dy for the second one - By @e d and @e d for the third one + By @a dx and @a dy for the second one + By @a d and @a d for the third one - @sa IncBy() + @see IncBy() */ void DecBy(const wxSize& size); void DecBy(int dx, int dy); @@ -586,7 +567,7 @@ public: Decrements this object so that both of its dimensions are not greater than the corresponding dimensions of the @e size. - @sa IncTo() + @see IncTo() */ void DecTo(const wxSize& size); @@ -603,12 +584,11 @@ public: //@{ /** Increases the size in x- and y- directions - By @e size.x and @e size.y for the first overload - By @e dx and @e dy for the second one - By @e d and @e d for the third one + By @a dx and @a dy for the second one + By @a d and @a d for the third one - @sa DecBy() + @see DecBy() */ void IncBy(const wxSize& size); void IncBy(int dx, int dy); @@ -619,7 +599,7 @@ public: Increments this object so that both of its dimensions are not less than the corresponding dimensions of the @e size. - @sa DecTo() + @see DecTo() */ void IncTo(const wxSize& size); @@ -627,7 +607,6 @@ public: Returns @true if neither of the size object components is equal to -1, which is used as default for the size values in wxWidgets (hence the predefined @c wxDefaultSize has both of its components equal to -1). - This method is typically used before calling SetDefaults(). */ @@ -656,7 +635,6 @@ public: Scales the dimensions of this object by the given factors. If you want to scale both dimensions by the same factor you can also use the @ref operators() "operator *=" - Returns a reference to this object (so that you can concatenate other operations in the same line). */ @@ -665,14 +643,14 @@ public: /** Sets the width and height members. */ -#define void Set(int width, int height) /* implementation is private */ + void Set(int width, int height); /** Combine this size object with another one replacing the default (i.e. equal to -1) components of this object with those of the other. It is typically used like this: - @sa IsFullySpecified() + @see IsFullySpecified() */ void SetDefaults(const wxSize& sizeDefault); @@ -741,16 +719,13 @@ public: to the pen list, and returns it. @param colour - Colour object. - + Colour object. @param colourName - Colour name, which should be in the colour database. - + Colour name, which should be in the colour database. @param width - Width of pen. - + Width of pen. @param style - Pen style. See wxPen::wxPen for a list of styles. + Pen style. See wxPen::wxPen for a list of styles. */ wxPen* FindOrCreatePen(const wxColour& colour, int width, int style); @@ -771,8 +746,8 @@ public: are currently defaulting to the whole display until a way is found to provide this info for all window managers, etc. */ -void wxClientDisplayRect(int * x, int * y, int * width, - int * height); +void wxClientDisplayRect(int* x, int* y, int* width, + int* height); wxRect wxGetClientDisplayRect(); //@} @@ -780,7 +755,7 @@ wxRect wxGetClientDisplayRect(); /** Returns the display size in pixels. */ -void wxDisplaySize(int * width, int * height); +void wxDisplaySize(int* width, int* height); wxSize wxGetDisplaySize(); //@} @@ -788,7 +763,7 @@ wxSize wxGetDisplaySize(); /** Returns the display size in millimeters. */ -void wxDisplaySizeMM(int * width, int * height); +void wxDisplaySizeMM(int* width, int* height); wxSize wxGetDisplaySizeMM(); //@} @@ -797,9 +772,9 @@ wxSize wxGetDisplaySizeMM(); for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to avoid using @c #ifdefs when creating icons. - @sa @ref overview_wxbitmapoverview "Bitmaps and icons overview", wxBITMAP + @see @ref overview_wxbitmapoverview, wxBITMAP */ -#define wxICON() /* implementation is private */ +wxICON(); /** Returns @true if the display is colour, @false otherwise. @@ -811,7 +786,7 @@ bool wxColourDisplay(); for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to avoid using @c #ifdefs when creating bitmaps. - @sa @ref overview_wxbitmapoverview "Bitmaps and icons overview", wxICON + @see @ref overview_wxbitmapoverview, wxICON */ #define wxBITMAP() /* implementation is private */ diff --git a/interface/glcanvas.h b/interface/glcanvas.h index 0c26b513c5..5b015bb87e 100644 --- a/interface/glcanvas.h +++ b/interface/glcanvas.h @@ -48,24 +48,22 @@ public: Constructor. @param win - The canvas that is used to initialize this context. This parameter is needed - only temporarily, - and the caller may do anything with it (e.g. destroy the window) after the + The canvas that is used to initialize this context. This parameter is + needed only temporarily, + and the caller may do anything with it (e.g. destroy the window) after the constructor returned. - - It will be possible to bind (make current) this context to any other wxGLCanvas - that has been created - with equivalent attributes as win. - + It will be possible to bind (make current) this context to any other + wxGLCanvas that has been created + with equivalent attributes as win. @param other - Context to share display lists with or @NULL (the default) for no sharing. + Context to share display lists with or @NULL (the default) for no sharing. */ - wxGLContext(wxGLCanvas* win, const wxGLContext* other=@NULL); + wxGLContext(wxGLCanvas* win, const wxGLContext* other = NULL); /** Makes the OpenGL state that is represented by this rendering context current with the wxGLCanvas @e win. - Note that @e win can be a different wxGLCanvas window than the one that was + Note that @a win can be a different wxGLCanvas window than the one that was passed to the constructor of this rendering context. If @e RC is an object of type wxGLContext, the statements @e RC.SetCurrent(win); and @e win.SetCurrent(RC); are equivalent, @@ -123,63 +121,56 @@ public: /** Creates a window with the given parameters. Notice that you need to create and use a wxGLContext to output to this window. - If @param attribList is not specified, double buffered RGBA mode is used. parent - Pointer to a parent window. - + Pointer to a parent window. @param id - Window identifier. If -1, will automatically create an identifier. - + Window identifier. If -1, will automatically create an identifier. @param pos - Window position. wxDefaultPosition is (-1, -1) which indicates that wxWidgets - should generate a default position for the window. - + Window position. wxDefaultPosition is (-1, -1) which indicates that + wxWidgets + should generate a default position for the window. @param size - Window size. wxDefaultSize is (-1, -1) which indicates that wxWidgets should - generate a default size for the window. If no suitable size can be found, the - window will be sized to 20x20 pixels so that the window is visible but obviously not correctly sized. - + Window size. wxDefaultSize is (-1, -1) which indicates that wxWidgets should + generate a default size for the window. If no suitable size can be found, + the window will be sized to 20x20 pixels so that the window is visible but obviously not correctly sized. @param style - Window style. - + Window style. @param name - Window name. - + Window name. @param attribList - Array of integers. With this parameter you can set the device context + Array of integers. With this parameter you can set the device context attributes associated to this window. - This array is zero-terminated: it should be set up with constants described in - the table above. - If a constant should be followed by a value, put it in the next array position. - For example, the WX_GL_DEPTH_SIZE should be followed by the value that + This array is zero-terminated: it should be set up with constants described + in the table above. + If a constant should be followed by a value, put it in the next array + position. + For example, the WX_GL_DEPTH_SIZE should be followed by the value that indicates the number of - bits for the depth buffer, so: - + bits for the depth buffer, so: @param palette - Palette for indexed colour (i.e. non WX_GL_RGBA) mode. - Ignored under most platforms. + Palette for indexed colour (i.e. non WX_GL_RGBA) mode. + Ignored under most platforms. */ wxGLCanvas(wxWindow* parent, wxWindowID id = wxID_ANY, - const int* attribList = @NULL, + const int* attribList = NULL, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, - long style=0, - const wxString& name="GLCanvas", + long style = 0, + const wxString& name = "GLCanvas", const wxPalette& palette = wxNullPalette); /** Determines if a canvas having the specified attributes is available. - Returns @true if attributes are supported. @param attribList - See attribList for wxGLCanvas(). + See attribList for wxGLCanvas(). */ - static bool IsDisplaySupported(const int * attribList = @NULL); + static bool IsDisplaySupported(const int* attribList = NULL); /** Sets the current colour for this window (using @c glcolor3f()), using the @@ -189,15 +180,12 @@ public: /** Makes the OpenGL state that is represented by the OpenGL rendering context - @e context current, i.e. it will be used by all subsequent OpenGL calls. - + @a context current, i.e. it will be used by all subsequent OpenGL calls. This is equivalent to wxGLContext::SetCurrent called with this window as parameter. - Note that this function may only be called when the window is shown on screen, in particular it can't usually be called from the constructor as the window isn't yet shown at this moment. - Returns @false if an error occurred. */ bool SetCurrent(const wxGLContext context); @@ -206,7 +194,6 @@ public: Swaps the double-buffer of this window, making the back-buffer the front-buffer and vice versa, so that the output of the previous OpenGL commands is displayed on the window. - Returns @false if an error occurred. */ bool SwapBuffers(); diff --git a/interface/graphics.h b/interface/graphics.h index 88710b99f8..2e784b8724 100644 --- a/interface/graphics.h +++ b/interface/graphics.h @@ -133,7 +133,7 @@ public: Returns the native path (CGPathRef for Core Graphics, Path pointer for GDIPlus and a cairo_path_t pointer for cairo). */ - void * GetNativePath(); + void* GetNativePath(); //@{ /** @@ -221,7 +221,7 @@ public: /** Creates a wxGraphicsContext from a wxWindow. - @sa wxGraphicsRenderer:: CreateContext + @see wxGraphicsRenderer:: CreateContext */ wxGraphicsContext* Create(const wxWindowDC& dc); wxGraphicsContext* Create(wxWindow* window); @@ -245,14 +245,14 @@ public: Creates a wxGraphicsContext from a native window. - @sa wxGraphicsRenderer:: CreateContextFromNativeContext + @see wxGraphicsRenderer:: CreateContextFromNativeContext */ - wxGraphicsContext* CreateFromNative(void * context); + wxGraphicsContext* CreateFromNative(void* context); /** - @sa wxGraphicsRenderer:: CreateContextFromNativeWindow + @see wxGraphicsRenderer:: CreateContextFromNativeWindow */ - wxGraphicsContext* CreateFromNativeWindow(void * window); + wxGraphicsContext* CreateFromNativeWindow(void* window); /** Creates a native brush, having a linear gradient, starting at (x1,y1) with @@ -359,11 +359,11 @@ public: Returns the native context (CGContextRef for Core Graphics, Graphics pointer for GDIPlus and cairo_t pointer for cairo). */ - void * GetNativeContext(); + void* GetNativeContext(); /** - Fills the @e widths array with the widths from the beginning of - @e text to the corresponding character of @e text. + Fills the @a widths array with the widths from the beginning of + @a text to the corresponding character of @e text. */ void GetPartialTextExtents(const wxString& text, wxArrayDouble& widths); @@ -371,9 +371,9 @@ public: /** Gets the dimensions of the string using the currently selected font. @e string is the text string to measure, @e w and @e h are - the total width and height respectively, @e descent is the + the total width and height respectively, @a descent is the dimension from the baseline of the font to the bottom of the - descender, and @e externalLeading is any extra vertical space added + descender, and @a externalLeading is any extra vertical space added to the font by the font designer (usually is zero). */ void GetTextExtent(const wxString& text, wxDouble* width, @@ -480,20 +480,20 @@ public: /** Creates a wxGraphicsContext from a wxWindow. */ - wxGraphicsContext * CreateContext(const wxWindowDC& dc); - wxGraphicsContext * CreateContext(wxWindow* window); + wxGraphicsContext* CreateContext(const wxWindowDC& dc); + wxGraphicsContext* CreateContext(wxWindow* window); //@} /** Creates a wxGraphicsContext from a native context. This native context must be eg a CGContextRef for Core Graphics, a Graphics pointer for GDIPlus or a cairo_t pointer for cairo. */ - wxGraphicsContext * CreateContextFromNativeContext(void * context); + wxGraphicsContext* CreateContextFromNativeContext(void* context); /** Creates a wxGraphicsContext from a native window. */ - wxGraphicsContext * CreateContextFromNativeWindow(void * window); + wxGraphicsContext* CreateContextFromNativeWindow(void* window); /** Creates a native graphics font from a wxFont and a text colour. @@ -621,15 +621,15 @@ public: /** Returns the component values of the matrix via the argument pointers. */ -#define void Get(wxDouble* a=@NULL, wxDouble* b=@NULL, wxDouble* c=@NULL, - wxDouble* d=@NULL, wxDouble* tx=@NULL, - wxDouble* ty=@NULL) /* implementation is private */ + void Get(wxDouble* a = NULL, wxDouble* b = NULL, wxDouble* c = NULL, + wxDouble* d = NULL, wxDouble* tx = NULL, + wxDouble* ty = NULL); /** Returns the native representation of the matrix. For CoreGraphics this is a CFAffineMatrix pointer. For GDIPlus a Matrix Pointer and for Cairo a cairo_matrix_t pointer. */ - void * GetNativeMatrix(); + void* GetNativeMatrix(); /** Inverts the matrix. @@ -660,9 +660,9 @@ public: Sets the matrix to the respective values (default values are the identity matrix) */ -#define void Set(wxDouble a = 1.0, wxDouble b = 0.0, wxDouble c = 0.0, - wxDouble d = 1.0, wxDouble tx = 0.0, - wxDouble ty = 0.0) /* implementation is private */ + void Set(wxDouble a = 1.0, wxDouble b = 0.0, wxDouble c = 0.0, + wxDouble d = 1.0, wxDouble tx = 0.0, + wxDouble ty = 0.0); /** Applies this matrix to a distance (ie. performs all transforms except diff --git a/interface/grid.h b/interface/grid.h index b0a5ee33e1..d10b3ebf9c 100644 --- a/interface/grid.h +++ b/interface/grid.h @@ -24,10 +24,9 @@ class wxGridCellFloatRenderer : public wxGridCellStringRenderer public: /** @param width - Minimum number of characters to be shown. - + Minimum number of characters to be shown. @param precision - Number of digits after the decimal dot. + Number of digits after the decimal dot. */ wxGridCellFloatRenderer(int width = -1, int precision = -1); @@ -186,7 +185,7 @@ public: /** */ - wxGrid * GetView(); + wxGrid* GetView(); /** @@ -367,7 +366,7 @@ public: Show or hide the edit control, use the specified attributes to set colours/fonts for it. */ - void Show(bool show, wxGridCellAttr* attr = @NULL); + void Show(bool show, wxGridCellAttr* attr = NULL); /** If the editor is enabled by clicking on the cell, this method will be @@ -456,19 +455,17 @@ public: //@{ /** @param count - Number of strings from which the user can choose. - + Number of strings from which the user can choose. @param choices - An array of strings from which the user can choose. - + An array of strings from which the user can choose. @param allowOthers - If allowOthers is @true, the user can type a string not in choices array. + If allowOthers is @true, the user can type a string not in choices array. */ wxGridCellChoiceEditor(size_t count = 0, - const wxString choices[] = @NULL, - bool allowOthers = @false); + const wxString choices[] = NULL, + bool allowOthers = false); wxGridCellChoiceEditor(const wxArrayString& choices, - bool allowOthers = @false); + bool allowOthers = false); //@} /** @@ -553,11 +550,11 @@ public: wxObject* obj, const wxGridCellCoords& topLeft, const wxGridCellCoords& bottomRight, - bool sel = @true, - bool control = @false, - bool shift = @false, - bool alt = @false, - bool meta = @false); + bool sel = true, + bool control = false, + bool shift = false, + bool alt = false, + bool meta = false); //@} /** @@ -647,7 +644,6 @@ public: Draw the given cell on the provided DC inside the given rectangle using the style specified by the attribute and the default or selected state corresponding to the isSelected value. - This pure virtual function has a default implementation which will prepare the DC using the given attribute: it will draw the rectangle with the background colour from attr and set the text colour and font. @@ -725,10 +721,10 @@ public: int rowOrCol = -1, int x = -1, int y = -1, - bool control = @false, - bool shift = @false, - bool alt = @false, - bool meta = @false); + bool control = false, + bool shift = false, + bool alt = false, + bool meta = false); //@} /** @@ -894,8 +890,8 @@ public: bool IsReadOnly(); /** - Sets the alignment. @e hAlign can be one of @c wxALIGN_LEFT, - @c wxALIGN_CENTRE or @c wxALIGN_RIGHT and @e vAlign can be one + Sets the alignment. @a hAlign can be one of @c wxALIGN_LEFT, + @c wxALIGN_CENTRE or @c wxALIGN_RIGHT and @a vAlign can be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM. */ void SetAlignment(int hAlign, int vAlign); @@ -923,7 +919,7 @@ public: /** */ - void SetReadOnly(bool isReadOnly = @true); + void SetReadOnly(bool isReadOnly = true); /** takes ownership of the pointer @@ -981,11 +977,11 @@ public: wxGridEvent(int id, wxEventType type, wxObject* obj, int row = -1, int col = -1, int x = -1, int y = -1, - bool sel = @true, - bool control = @false, - bool shift = @false, - bool alt = @false, - bool meta = @false); + bool sel = true, + bool control = false, + bool shift = false, + bool alt = false, + bool meta = false); //@} /** @@ -1049,10 +1045,9 @@ class wxGridCellFloatEditor : public wxGridCellTextEditor public: /** @param width - Minimum number of characters to be shown. - + Minimum number of characters to be shown. @param precision - Number of digits after the decimal dot. + Number of digits after the decimal dot. */ wxGridCellFloatEditor(int width = -1, int precision = -1); @@ -1074,7 +1069,7 @@ public: directly. It will set up default instances of the other classes and manage them for you. For more complex applications you can derive your own classes for custom grid views, grid data tables, cell editors and - renderers. The @ref overview_gridoverview "wxGrid classes overview" has + renderers. The @ref overview_gridoverview has examples of simple and more complex applications, explains the relationship between the various grid classes and has a summary of the keyboard shortcuts and mouse functions provided by wxGrid. @@ -1144,22 +1139,20 @@ public: /** Appends one or more new columns to the right of the grid and returns @true if successful. The updateLabels argument is not used at present. - If you are using a derived grid table class you will need to override wxGridTableBase::AppendCols. See InsertCols() for further information. */ - bool AppendCols(int numCols = 1, bool updateLabels = @true); + bool AppendCols(int numCols = 1, bool updateLabels = true); /** Appends one or more new rows to the bottom of the grid and returns @true if successful. The updateLabels argument is not used at present. - If you are using a derived grid table class you will need to override wxGridTableBase::AppendRows. See InsertRows() for further information. */ - bool AppendRows(int numRows = 1, bool updateLabels = @true); + bool AppendRows(int numRows = 1, bool updateLabels = true); /** Automatically sets the height and width of all rows and columns to fit their @@ -1177,21 +1170,21 @@ public: calculated width will also be set as the minimal width for the column. */ - void AutoSizeColumn(int col, bool setAsMin = @true); + void AutoSizeColumn(int col, bool setAsMin = true); /** Automatically sizes all columns to fit their contents. If setAsMin is @true the calculated widths will also be set as the minimal widths for the columns. */ - void AutoSizeColumns(bool setAsMin = @true); + void AutoSizeColumns(bool setAsMin = true); /** Automatically sizes the row to fit its contents. If setAsMin is @true the calculated height will also be set as the minimal height for the row. */ - void AutoSizeRow(int row, bool setAsMin = @true); + void AutoSizeRow(int row, bool setAsMin = true); /** Automatically adjusts height of the row to fit its label. @@ -1203,7 +1196,7 @@ public: calculated heights will also be set as the minimal heights for the rows. */ - void AutoSizeRows(bool setAsMin = @true); + void AutoSizeRows(bool setAsMin = true); /** AutoSizeColumn() @@ -1239,7 +1232,7 @@ public: modification can be enclosed between BeginBatch and EndBatch calls to avoid screen flicker. The final EndBatch will cause the grid to be repainted. - @sa wxGridUpdateLocker + @see wxGridUpdateLocker */ void BeginBatch(); @@ -1248,8 +1241,8 @@ public: limited by TopLeft and BottomRight cell in device coords and clipped to the client size of the grid window. */ - wxRect BlockToDeviceRect(const wxGridCellCoords & topLeft, - const wxGridCellCoords & bottomRight); + wxRect BlockToDeviceRect(const wxGridCellCoords& topLeft, + const wxGridCellCoords& bottomRight); /** Returns @true if columns can be moved by dragging with the mouse. Columns can be @@ -1364,7 +1357,6 @@ public: Call this directly after the grid constructor. When you use this function wxGrid will create and manage a simple table of string values for you. All of the grid data will be stored in memory. - For applications with more complex data types or relationships, or for dealing with very large datasets, you should derive your own grid table class and pass a table object to the grid with SetTable(). @@ -1399,25 +1391,23 @@ public: Deletes one or more columns from a grid starting at the specified position and returns @true if successful. The updateLabels argument is not used at present. - If you are using a derived grid table class you will need to override wxGridTableBase::DeleteCols. See InsertCols() for further information. */ bool DeleteCols(int pos = 0, int numCols = 1, - bool updateLabels = @true); + bool updateLabels = true); /** Deletes one or more rows from a grid starting at the specified position and returns @true if successful. The updateLabels argument is not used at present. - If you are using a derived grid table class you will need to override wxGridTableBase::DeleteRows. See InsertRows() for further information. */ bool DeleteRows(int pos = 0, int numRows = 1, - bool updateLabels = @true); + bool updateLabels = true); /** Disables in-place editing of grid cells. @@ -1457,28 +1447,28 @@ public: either a wxEVT_GRID_EDITOR_SHOWN or wxEVT_GRID_EDITOR_HIDDEN event. */ - void EnableCellEditControl(bool enable = @true); + void EnableCellEditControl(bool enable = true); /** Enables or disables column moving by dragging with the mouse. */ - void EnableDragColMove(bool enable = @true); + void EnableDragColMove(bool enable = true); /** Enables or disables column sizing by dragging with the mouse. */ - void EnableDragColSize(bool enable = @true); + void EnableDragColSize(bool enable = true); /** Enables or disables row and column resizing by dragging gridlines with the mouse. */ - void EnableDragGridSize(bool enable = @true); + void EnableDragGridSize(bool enable = true); /** Enables or disables row sizing by dragging with the mouse. */ - void EnableDragRowSize(bool enable = @true); + void EnableDragRowSize(bool enable = true); /** If the edit argument is @false this function sets the whole grid as read-only. @@ -1491,17 +1481,16 @@ public: wxGridCellAttribute::SetReadOnly. For single cells you can also use the shortcut function SetReadOnly(). - For more information about controlling grid cell attributes see the wxGridCellAttr cell attribute class and the - @ref overview_gridoverview "wxGrid classes overview". + @ref overview_gridoverview. */ void EnableEditing(bool edit); /** Turns the drawing of grid lines on or off. */ - void EnableGridLines(bool enable = @true); + void EnableGridLines(bool enable = true); /** Decrements the grid's batch count. When the count is greater than zero @@ -1512,14 +1501,14 @@ public: BeginBatch and EndBatch calls to avoid screen flicker. The final EndBatch will cause the grid to be repainted. - @sa wxGridUpdateLocker + @see wxGridUpdateLocker */ void EndBatch(); /** Overridden wxWindow method. */ -#define void Fit() /* implementation is private */ + void Fit(); /** Causes immediate repainting of the grid. Use this instead of the usual @@ -1537,7 +1526,6 @@ public: /** Sets the arguments to the horizontal and vertical text alignment values for the grid cell at the specified location. - Horizontal alignment will be one of wxALIGN_LEFT, wxALIGN_CENTRE or wxALIGN_RIGHT. @@ -1552,7 +1540,6 @@ public: /** Returns a pointer to the editor for the cell at the specified location. - See wxGridCellEditor and the @ref overview_gridoverview "wxGrid overview" for more information about cell editors and renderers. @@ -1566,7 +1553,6 @@ public: /** Returns a pointer to the renderer for the grid cell at the specified location. - See wxGridCellRenderer and the @ref overview_gridoverview "wxGrid overview" for more information about cell editors and renderers. @@ -1585,13 +1571,11 @@ public: grid object automatically uses a default grid table of string values you use this function together with SetCellValue() to access cell values. - For more complex applications where you have derived your own grid table class that contains various data types (e.g. numeric, boolean or user-defined custom types) then you only use this function for those cells that contain string values. - See wxGridTableBase::CanGetValueAs and the @ref overview_gridoverview "wxGrid overview" for more information. */ @@ -1608,14 +1592,12 @@ public: Returns the pen used for vertical grid lines. This virtual function may be overridden in derived classes in order to change the appearance of individual grid lines for the given column @e col. - See GetRowGridLinePen() for an example. */ wxPen GetColGridLinePen(int col); /** Sets the arguments to the current column label alignment values. - Horizontal alignment will be one of wxALIGN_LEFT, wxALIGN_CENTRE or wxALIGN_RIGHT. @@ -1673,7 +1655,6 @@ public: /** Sets the arguments to the current default horizontal and vertical text alignment values. - Horizontal alignment will be one of wxALIGN_LEFT, wxALIGN_CENTRE or wxALIGN_RIGHT. @@ -1708,7 +1689,6 @@ public: /** Returns a pointer to the current default grid cell editor. - See wxGridCellEditor and the @ref overview_gridoverview "wxGrid overview" for more information about cell editors and renderers. @@ -1733,13 +1713,12 @@ public: derived classes in order to change the appearance of grid lines. Note that currently the pen width must be 1. - @sa GetColGridLinePen(), GetRowGridLinePen() + @see GetColGridLinePen(), GetRowGridLinePen() */ wxPen GetDefaultGridLinePen(); /** Returns a pointer to the current default grid cell renderer. - See wxGridCellRenderer and the @ref overview_gridoverview "wxGrid overview" for more information about cell editors and renderers. @@ -1779,7 +1758,7 @@ public: /** Returns the colour used for grid lines. - @sa GetDefaultGridLinePen() + @see GetDefaultGridLinePen() */ wxColour GetGridLineColour(); @@ -1820,14 +1799,12 @@ public: Returns the pen used for horizontal grid lines. This virtual function may be overridden in derived classes in order to change the appearance of individual grid line for the given row @e row. - Example: */ wxPen GetRowGridLinePen(int row); /** Sets the arguments to the current row label alignment values. - Horizontal alignment will be one of wxLEFT, wxCENTRE or wxRIGHT. Vertical alignment will be one of wxTOP, wxCENTRE or wxBOTTOM. @@ -1868,14 +1845,14 @@ public: /** Returns the number of pixels per horizontal scroll increment. The default is 15. - @sa GetScrollLineY(), SetScrollLineX(), SetScrollLineY() + @see GetScrollLineY(), SetScrollLineX(), SetScrollLineY() */ int GetScrollLineX(); /** Returns the number of pixels per vertical scroll increment. The default is 15. - @sa GetScrollLineX(), SetScrollLineX(), SetScrollLineY() + @see GetScrollLineX(), SetScrollLineX(), SetScrollLineY() */ int GetScrollLineY(); @@ -1924,7 +1901,7 @@ public: /** Returns a base pointer to the current table object. */ - wxGridTableBase * GetTable(); + wxGridTableBase* GetTable(); /** Returned number of whole cols visible. @@ -1980,7 +1957,6 @@ public: /** NB: @e never access m_row/col arrays directly because they are created on demand, @e always use accessor functions instead! - Init the m_rowHeights/Bottoms arrays with default values. */ void InitRowHeights(); @@ -1990,7 +1966,6 @@ public: specified position and returns @true if successful. The updateLabels argument is not used at present. - The sequence of actions begins with the grid object requesting the underlying grid table to insert new columns. If this is successful the table notifies the grid @@ -2003,14 +1978,13 @@ public: table class. */ bool InsertCols(int pos = 0, int numCols = 1, - bool updateLabels = @true); + bool updateLabels = true); /** Inserts one or more new rows into a grid with the first new row at the specified position and returns @true if successful. The updateLabels argument is not used at present. - The sequence of actions begins with the grid object requesting the underlying grid table to insert new rows. If this is successful the table notifies the grid and @@ -2023,7 +1997,7 @@ public: table class. */ bool InsertRows(int pos = 0, int numRows = 1, - bool updateLabels = @true); + bool updateLabels = true); /** Returns @true if the in-place edit control is currently enabled. @@ -2068,9 +2042,9 @@ public: partially visible in the grid window. */ - bool IsVisible(int row, int col, bool wholeCellVisible = @true); + bool IsVisible(int row, int col, bool wholeCellVisible = true); bool IsVisible(const wxGridCellCoords& coords, - bool wholeCellVisible = @true); + bool wholeCellVisible = true); //@} //@{ @@ -2248,10 +2222,10 @@ public: */ void SelectBlock(int topRow, int leftCol, int bottomRow, int rightCol, - bool addToSelected = @false); + bool addToSelected = false); void SelectBlock(const wxGridCellCoords& topLeft, const wxGridCellCoords& bottomRight, - bool addToSelected = @false); + bool addToSelected = false); //@} /** @@ -2259,14 +2233,14 @@ public: selection will be deselected; if @true the column will be added to the existing selection. */ - void SelectCol(int col, bool addToSelected = @false); + void SelectCol(int col, bool addToSelected = false); /** Selects the specified row. If addToSelected is @false then any existing selection will be deselected; if @true the row will be added to the existing selection. */ - void SelectRow(int row, bool addToSelected = @false); + void SelectRow(int row, bool addToSelected = false); /** ClearSelection() @@ -2293,7 +2267,6 @@ public: /** Sets the horizontal and vertical alignment for grid cell text at the specified location. - Horizontal alignment should be one of wxALIGN_LEFT, wxALIGN_CENTRE or wxALIGN_RIGHT. @@ -2313,7 +2286,6 @@ public: /** Sets the editor for the grid cell at the specified location. The grid will take ownership of the pointer. - See wxGridCellEditor and the @ref overview_gridoverview "wxGrid overview" for more information about cell editors and renderers. @@ -2328,7 +2300,6 @@ public: /** Sets the renderer for the grid cell at the specified location. The grid will take ownership of the pointer. - See wxGridCellRenderer and the @ref overview_gridoverview "wxGrid overview" for more information about cell editors and renderers. @@ -2352,15 +2323,12 @@ public: grid object automatically uses a default grid table of string values you use this function together with GetCellValue() to access cell values. - For more complex applications where you have derived your own grid table class that contains various data types (e.g. numeric, boolean or user-defined custom types) then you only use this function for those cells that contain string values. - The last form is for backward compatibility only. - See wxGridTableBase::CanSetValueAs and the @ref overview_gridoverview "wxGrid overview" for more information. */ @@ -2372,10 +2340,9 @@ public: /** Sets the cell attributes for all cells in the specified column. - For more information about controlling grid cell attributes see the wxGridCellAttr cell attribute class and the - @ref overview_gridoverview "wxGrid classes overview". + @ref overview_gridoverview. */ void SetColAttr(int col, wxGridCellAttr* attr); @@ -2407,10 +2374,8 @@ public: /** Sets the horizontal and vertical alignment of column label text. - Horizontal alignment should be one of wxALIGN_LEFT, wxALIGN_CENTRE or wxALIGN_RIGHT. - Vertical alignment should be one of wxALIGN_TOP, wxALIGN_CENTRE or wxALIGN_BOTTOM. */ @@ -2418,8 +2383,7 @@ public: /** Sets the height of the column labels. - - If @e height equals to @c wxGRID_AUTOSIZE then height is calculated + If @a height equals to @c wxGRID_AUTOSIZE then height is calculated automatically so that no label is truncated. Note that this could be slow for a large table. */ @@ -2465,11 +2429,9 @@ public: /** Sets the width of the specified column. - This function does not refresh the grid. If you are calling it outside of a BeginBatch / EndBatch block you can use ForceRefresh() to see the changes. - Automatically sizes the column to fit its contents. If setAsMin is @true the calculated width will also be set as the minimal width for the column. @@ -2478,10 +2440,8 @@ public: /** Sets the default horizontal and vertical alignment for grid cell text. - Horizontal alignment should be one of wxALIGN_LEFT, wxALIGN_CENTRE or wxALIGN_RIGHT. - Vertical alignment should be one of wxALIGN_TOP, wxALIGN_CENTRE or wxALIGN_BOTTOM. */ @@ -2508,12 +2468,11 @@ public: the grid unless resizeExistingCols is @true. */ void SetDefaultColSize(int width, - bool resizeExistingCols = @false); + bool resizeExistingCols = false); /** Sets the default editor for grid cells. The grid will take ownership of the pointer. - See wxGridCellEditor and the @ref overview_gridoverview "wxGrid overview" for more information about cell editors and renderers. @@ -2523,7 +2482,6 @@ public: /** Sets the default renderer for grid cells. The grid will take ownership of the pointer. - See wxGridCellRenderer and the @ref overview_gridoverview "wxGrid overview" for more information about cell editors and renderers. @@ -2536,7 +2494,7 @@ public: to the grid unless resizeExistingRows is @true. */ void SetDefaultRowSize(int height, - bool resizeExistingRows = @false); + bool resizeExistingRows = false); /** Set the grid cursor to the specified cell. @@ -2573,18 +2531,18 @@ public: /** Common part of AutoSizeColumn/Row() and GetBestSize() */ - int SetOrCalcColumnSizes(bool calcOnly, bool setAsMin = @true); + int SetOrCalcColumnSizes(bool calcOnly, bool setAsMin = true); /** */ - int SetOrCalcRowSizes(bool calcOnly, bool setAsMin = @true); + int SetOrCalcRowSizes(bool calcOnly, bool setAsMin = true); /** Makes the cell at the specified location read-only or editable. See also IsReadOnly(). */ - void SetReadOnly(int row, int col, bool isReadOnly = @true); + void SetReadOnly(int row, int col, bool isReadOnly = true); /** Sets the cell attributes for all cells in the specified row. @@ -2595,10 +2553,8 @@ public: /** Sets the horizontal and vertical alignment of row label text. - Horizontal alignment should be one of wxALIGN_LEFT, wxALIGN_CENTRE or wxALIGN_RIGHT. - Vertical alignment should be one of wxALIGN_TOP, wxALIGN_CENTRE or wxALIGN_BOTTOM. */ @@ -2606,8 +2562,7 @@ public: /** Sets the width of the row labels. - - If @e width equals @c wxGRID_AUTOSIZE then width is calculated automatically + If @a width equals @c wxGRID_AUTOSIZE then width is calculated automatically so that no label is truncated. Note that this could be slow for a large table. */ void SetRowLabelSize(int width); @@ -2646,11 +2601,9 @@ public: /** Sets the height of the specified row. - This function does not refresh the grid. If you are calling it outside of a BeginBatch / EndBatch block you can use ForceRefresh() to see the changes. - Automatically sizes the column to fit its contents. If setAsMin is @true the calculated width will also be set as the minimal width for the column. @@ -2662,7 +2615,7 @@ public: Sometimes wxGrid has trouble setting the scrollbars correctly due to rounding errors: setting this to 1 can help. - @sa GetScrollLineX(), GetScrollLineY(), SetScrollLineY() + @see GetScrollLineX(), GetScrollLineY(), SetScrollLineY() */ void SetScrollLineX(int x); @@ -2671,7 +2624,7 @@ public: Sometimes wxGrid has trouble setting the scrollbars correctly due to rounding errors: setting this to 1 can help. - @sa GetScrollLineX(), GetScrollLineY(), SetScrollLineX() + @see GetScrollLineX(), GetScrollLineY(), SetScrollLineX() */ void SetScrollLineY(int y); @@ -2689,13 +2642,11 @@ public: Set the selection behaviour of the grid. @param wxGridSelectCells() - The default mode where individual cells are selected. - + The default mode where individual cells are selected. @param wxGridSelectRows() - Selections will consist of whole rows. - + Selections will consist of whole rows. @param wxGridSelectColumns() - Selections will consist of whole columns. + Selections will consist of whole columns. */ void SetSelectionMode(wxGrid::wxGridSelectionModes selmode); @@ -2705,13 +2656,12 @@ public: after the grid constructor and before using the grid object. If takeOwnership is set to @true then the table will be deleted by the wxGrid destructor. - Use this function instead of CreateGrid() when your application involves complex or non-string data or data sets that are too large to fit wholly in memory. */ - bool SetTable(wxGridTableBase* table, bool takeOwnership = @false, + bool SetTable(wxGridTableBase* table, bool takeOwnership = false, wxGrid::wxGridSelectionModes selmode = wxGrid::wxGridSelectCells); /** @@ -2721,7 +2671,7 @@ public: there is not native look for that. This option is useful when using wxGrid for displaying tables and not as a spread-sheet. */ - void SetUseNativeColLabels(bool native= @true); + void SetUseNativeColLabels(bool native = true); /** Displays the in-place cell edit control for the current cell. @@ -2730,13 +2680,12 @@ public: /** @param x - The x position to evaluate. - + The x position to evaluate. @param clipToMinMax - If @true, rather than returning wxNOT_FOUND, it returns either the first or last - column depending on whether x is too far to the left or right respectively. + If @true, rather than returning wxNOT_FOUND, it returns either the first or + last column depending on whether x is too far to the left or right respectively. */ - int XToCol(int x, bool clipToMinMax = @false); + int XToCol(int x, bool clipToMinMax = false); /** Returns the column whose right hand edge is close to the given logical x @@ -2781,7 +2730,7 @@ public: wxGridCellBoolEditor(); /** - Returns @true if the given @e value is equal to the string representation of + Returns @true if the given @a value is equal to the string representation of the truth value we currently use (see wxGridCellBoolEditor::UseStringValues). */ @@ -2789,7 +2738,6 @@ public: /** , @b const wxString&@e valueFalse = _T("")) - This method allows to customize the values returned by GetValue() method for the cell using this editor. By default, the default values of the arguments are used, i.e. @c "1" is returned if the cell is checked and an empty string @@ -2835,15 +2783,14 @@ class wxGridUpdateLocker public: /** Creates an object preventing the updates of the specified @e grid. The - parameter could be @NULL in which case nothing is done. If @e grid is + parameter could be @NULL in which case nothing is done. If @a grid is non-@NULL then the grid must exist for longer than wxGridUpdateLocker object itself. - The default constructor could be followed by a call to Create() to set the grid object later. */ - wxGridUpdateLocker(wxGrid * grid = @NULL); + wxGridUpdateLocker(wxGrid* grid = NULL); /** Destructor reenables updates for the grid this object is associated with. diff --git a/interface/hash.h b/interface/hash.h index 63a31c99a9..7def270604 100644 --- a/interface/hash.h +++ b/interface/hash.h @@ -27,8 +27,8 @@ class wxHashTable : public wxObject { public: /** - Constructor. @e key_type is one of wxKEY_INTEGER, or wxKEY_STRING, - and indicates what sort of keying is required. @e size is optional. + Constructor. @a key_type is one of wxKEY_INTEGER, or wxKEY_STRING, + and indicates what sort of keying is required. @a size is optional. */ wxHashTable(unsigned int key_type, int size = 1000); @@ -53,8 +53,8 @@ public: /** Deletes entry in hash table and returns the user's data (if found). */ - wxObject * Delete(long key); - wxObject * Delete(const wxString& key); + wxObject* Delete(long key); + wxObject* Delete(const wxString& key); //@} /** @@ -69,8 +69,8 @@ public: which has table constructor was used). */ - wxObject * Get(long key); - wxObject * Get(const char* key); + wxObject* Get(long key); + wxObject* Get(const char* key); //@} /** @@ -92,7 +92,7 @@ public: implemented as a @b wxNode. The user will probably only wish to use the @b GetData method to retrieve the data; the node may also be deleted. */ - wxHashTable::Node * Next(); + wxHashTable::Node* Next(); //@{ /** @@ -101,7 +101,7 @@ public: has table constructor was used). The key string is copied and stored by the hash table implementation. */ - void Put(long key, wxObject * object); - void Put(const char* key, wxObject * object); + void Put(long key, wxObject* object); + void Put(const char* key, wxObject* object); //@} }; diff --git a/interface/help.h b/interface/help.h index e35d2d6bd1..366f4473b8 100644 --- a/interface/help.h +++ b/interface/help.h @@ -80,7 +80,6 @@ class wxHelpController : public wxObject public: /** Constructs a help instance object, but does not invoke the help viewer. - If you provide a window, it will be used by some help controller classes, such as wxCHMHelpController, wxWinHelpController and wxHtmlHelpController, as the @@ -88,7 +87,7 @@ public: also change the parent window later with SetParentWindow(). */ - wxHelpController(wxWindow* parentWindow = @NULL); + wxHelpController(wxWindow* parentWindow = NULL); /** Destroys the help instance, closing down the viewer if it is running. @@ -98,16 +97,11 @@ public: /** If the help viewer is not running, runs it and displays the file at the given block number. - @e WinHelp: Refers to the context number. - @e MS HTML Help: Refers to the context number. - @e External HTML help: the same as for DisplaySection(). - @e wxHtmlHelpController: @e sectionNo is an identifier as specified in the @c .hhc file. See @ref overview_helpformat "Help files format". - This function is for backward compatibility only, and applications should use @ref displaysection() wxHelpController instead. */ @@ -121,7 +115,6 @@ public: /** Displays the section as a popup window using a context id. - Returns @false if unsuccessful or not implemented. */ virtual bool DisplayContextPopup(int contextId); @@ -129,14 +122,12 @@ public: //@{ /** If the help viewer is not running, runs it and displays the given section. - - @e WinHelp, MS HTML Help @e sectionNo is a context id. - - @e External HTML help: wxExtHelpController implements @e sectionNo as an id in + @e WinHelp, MS HTML Help @a sectionNo is a context id. + @e External HTML help: wxExtHelpController implements @a sectionNo as an id in a map file, which is of the form: - @e wxHtmlHelpController: @e sectionNo is an identifier as specified in the @c - .hhc file. See @ref overview_helpformat "Help files format". + @e wxHtmlHelpController: @a sectionNo is an identifier as specified in the @c + .hhc file. See @ref overview_helpformat "Help files format". See also the help sample for notes on how to specify section numbers for various help file formats. */ @@ -146,7 +137,6 @@ public: /** Displays the text in a popup window, if possible. - Returns @false if unsuccessful or not implemented. */ virtual bool DisplayTextPopup(const wxString& text, @@ -154,20 +144,18 @@ public: /** wxHtmlHelpController returns the frame, size and position. - For all other help controllers, this function does nothing and just returns @NULL. @param viewer - This defaults to "netscape" for wxExtHelpController. - + This defaults to "netscape" for wxExtHelpController. @param flags - This defaults to wxHELP_NETSCAPE for wxExtHelpController, indicating - that the viewer is a variant of Netscape Navigator. + This defaults to wxHELP_NETSCAPE for wxExtHelpController, indicating + that the viewer is a variant of Netscape Navigator. */ - virtual wxFrame * GetFrameParameters(const wxSize * size = @NULL, - const wxPoint * pos = @NULL, - bool * newFrameEachTime = @NULL); + virtual wxFrame* GetFrameParameters(const wxSize* size = NULL, + const wxPoint* pos = NULL, + bool* newFrameEachTime = NULL); /** Returns the window to be used as the parent for the help window. This window is @@ -184,7 +172,6 @@ public: This must be called directly after the help instance object is created and before any attempts to communicate with the viewer. - You may omit the file extension and a suitable one will be chosen. For wxHtmlHelpController, the extensions zip, htb and hhp will be appended while searching for @@ -200,13 +187,10 @@ public: section. The optional parameter allows the search the index (wxHELP_SEARCH_INDEX) but this currently only supported by the wxHtmlHelpController. - @e WinHelp, MS HTML Help: If more than one match is found, the first topic is displayed. - @e External HTML help, simple wxHTML help: If more than one match is found, a choice of topics is displayed. - @e wxHtmlHelpController: see wxHtmlHelpController::KeywordSearch. */ virtual bool KeywordSearch(const wxString& keyWord, @@ -219,21 +203,18 @@ public: already displaying the specified file, it will not be reloaded. This member function may be used before each display call in case the user has opened another file. - wxHtmlHelpController ignores this call. */ virtual bool LoadFile(const wxString& file = ""); /** Overridable member called when this application's viewer is quit by the user. - This does not work for all help controllers. */ virtual bool OnQuit(); /** If the viewer is running, quits it by disconnecting. - For Windows Help, the viewer will only close if no other application is using it. */ @@ -242,14 +223,13 @@ public: /** For wxHtmlHelpController, the title is set (again with %s indicating the page title) and also the size and position of the frame if the frame is already - open. @e newFrameEachTime is ignored. - + open. @a newFrameEachTime is ignored. For all other help controllers this function has no effect. */ - virtual void SetFrameParameters(const wxString & title, - const wxSize & size, - const wxPoint & pos = wxDefaultPosition, - bool newFrameEachTime = @false); + virtual void SetFrameParameters(const wxString& title, + const wxSize& size, + const wxPoint& pos = wxDefaultPosition, + bool newFrameEachTime = false); /** Sets the window to be used as the parent for the help window. This is used @@ -260,7 +240,6 @@ public: /** Sets detailed viewer information. So far this is only relevant to wxExtHelpController. - Some examples of usage: */ virtual void SetViewer(const wxString& viewer, long flags); diff --git a/interface/html/helpctrl.h b/interface/html/helpctrl.h index a605e3fa83..516455866f 100644 --- a/interface/html/helpctrl.h +++ b/interface/html/helpctrl.h @@ -46,15 +46,14 @@ public: Constructor. */ wxHtmlHelpController(int style = wxHF_DEFAULT_STYLE, - wxWindow* parentWindow = @NULL); + wxWindow* parentWindow = NULL); //@{ /** Adds book (@ref overview_helpformat ".hhp file" - HTML Help Workshop project file) into the list of loaded books. This must be called at least once before displaying any help. - - @e bookFile or @e bookUrl may be either .hhp file or ZIP archive + @a bookFile or @a bookUrl may be either .hhp file or ZIP archive that contains arbitrary number of .hhp files in top-level directory. This ZIP archive must have .zip or .htb extension (the latter stands for "HTML book"). In other words, @c @@ -62,15 +61,13 @@ public: is possible and is the recommended way. @param showWaitMsg - If @true then a decoration-less window with progress message is displayed. - + If @true then a decoration-less window with progress message is displayed. @param bookFile - Help book filename. It is recommended to use this prototype - instead of the one taking URL, because it is less error-prone. - + Help book filename. It is recommended to use this prototype + instead of the one taking URL, because it is less error-prone. @param bookUrl - Help book URL (note that syntax of filename and URL is - different on most platforms) + Help book URL (note that syntax of filename and URL is + different on most platforms) */ bool AddBook(const wxFileName& bookFile, bool showWaitMsg); bool AddBook(const wxString& bookUrl, bool showWaitMsg); @@ -81,13 +78,13 @@ public: wxHF_DIALOG style, the controller uses a different dialog. */ - virtual wxHtmlHelpDialog* CreateHelpDialog(wxHtmlHelpData * data); + virtual wxHtmlHelpDialog* CreateHelpDialog(wxHtmlHelpData* data); /** This protected virtual method may be overridden so that the controller uses a different frame. */ - virtual wxHtmlHelpFrame* CreateHelpFrame(wxHtmlHelpData * data); + virtual wxHtmlHelpFrame* CreateHelpFrame(wxHtmlHelpData* data); //@{ /** @@ -111,7 +108,6 @@ public: Displays help window, focuses search panel and starts searching. Returns @true if the keyword was found. Optionally it searches through the index (mode = wxHELP_SEARCH_INDEX), default the content (mode = wxHELP_SEARCH_ALL). - @b Important: KeywordSearch searches only pages listed in .hhc file(s). You should list all pages in the contents file. */ @@ -130,7 +126,6 @@ public: forms are much faster to read. Default value is empty string (empty string means that no cached data are stored). Note that these files are @e not deleted when program exits. - Once created these cached files will be used in all subsequent executions of your application. If cached files become older than corresponding .hhp file (e.g. if you regenerate documentation) it will be refreshed. @@ -144,13 +139,10 @@ public: void SetTitleFormat(const wxString& format); /** - Associates @e config object with the controller. - + Associates @a config object with the controller. If there is associated config object, wxHtmlHelpController automatically reads and writes settings (including wxHtmlWindow's settings) when needed. - The only thing you must do is create wxConfig object and call UseConfig. - If you do not use @e UseConfig, wxHtmlHelpController will use default wxConfig object if available (for details see wxConfigBase::Get and @@ -194,16 +186,13 @@ class wxHtmlModalHelp public: /** @param parent - is the parent of the dialog. - + is the parent of the dialog. @param helpFile - is the HTML help file to show. - + is the HTML help file to show. @param topic - is an optional topic. If this is empty, the help contents will be shown. - + is an optional topic. If this is empty, the help contents will be shown. @param style - is a combination of the flags described in the wxHtmlHelpController + is a combination of the flags described in the wxHtmlHelpController documentation. */ wxHtmlModalHelp(wxWindow* parent, const wxString& helpFile, diff --git a/interface/html/helpdlg.h b/interface/html/helpdlg.h index 5def3cc722..c9cdd8c6c0 100644 --- a/interface/html/helpdlg.h +++ b/interface/html/helpdlg.h @@ -26,21 +26,20 @@ public: Constructor. For the values of @e style, please see the documentation for wxHtmlHelpController. */ - wxHtmlHelpDialog(wxHtmlHelpData* data = @NULL); + wxHtmlHelpDialog(wxHtmlHelpData* data = NULL); wxHtmlHelpDialog(wxWindow* parent, int wxWindowID, const wxString& title = wxEmptyString, int style = wxHF_DEFAULT_STYLE, - wxHtmlHelpData* data = @NULL); + wxHtmlHelpData* data = NULL); //@} /** You may override this virtual method to add more buttons to the help window's - toolbar. @e toolBar is a pointer to the toolbar and @e style is the style + toolbar. @a toolBar is a pointer to the toolbar and @a style is the style flag as passed to the Create method. - wxToolBar::Realize is called immediately after returning from this function. */ - virtual void AddToolbarButtons(wxToolBar * toolBar, int style); + virtual void AddToolbarButtons(wxToolBar* toolBar, int style); /** Creates the dialog. See @ref wxhtmlhelpdialog() "the constructor" @@ -68,7 +67,7 @@ public: void SetController(wxHtmlHelpController* contoller); /** - Sets the dialog's title format. @e format must contain exactly one "%s" + Sets the dialog's title format. @a format must contain exactly one "%s" (it will be replaced by the page title). */ void SetTitleFormat(const wxString& format); diff --git a/interface/html/helpfrm.h b/interface/html/helpfrm.h index d91bad2eba..e5affeb6bb 100644 --- a/interface/html/helpfrm.h +++ b/interface/html/helpfrm.h @@ -26,21 +26,20 @@ public: Constructor. For the values of @e style, please see the documentation for wxHtmlHelpController. */ - wxHtmlHelpFrame(wxHtmlHelpData* data = @NULL); + wxHtmlHelpFrame(wxHtmlHelpData* data = NULL); wxHtmlHelpFrame(wxWindow* parent, int wxWindowID, const wxString& title = wxEmptyString, int style = wxHF_DEFAULT_STYLE, - wxHtmlHelpData* data = @NULL); + wxHtmlHelpData* data = NULL); //@} /** You may override this virtual method to add more buttons to the help window's - toolbar. @e toolBar is a pointer to the toolbar and @e style is the style + toolbar. @a toolBar is a pointer to the toolbar and @a style is the style flag as passed to the Create method. - wxToolBar::Realize is called immediately after returning from this function. */ - virtual void AddToolbarButtons(wxToolBar * toolBar, int style); + virtual void AddToolbarButtons(wxToolBar* toolBar, int style); /** Creates the frame. See @ref wxhtmlhelpframe() "the constructor" @@ -68,7 +67,7 @@ public: void SetController(wxHtmlHelpController* contoller); /** - Sets the frame's title format. @e format must contain exactly one "%s" + Sets the frame's title format. @a format must contain exactly one "%s" (it will be replaced by the page title). */ void SetTitleFormat(const wxString& format); diff --git a/interface/html/helpwnd.h b/interface/html/helpwnd.h index c7d6add0a1..42123e7905 100644 --- a/interface/html/helpwnd.h +++ b/interface/html/helpwnd.h @@ -44,29 +44,26 @@ public: //@{ /** Constructor. - Constructor. For the values of @e helpStyle, please see the documentation for wxHtmlHelpController. */ - wxHtmlHelpWindow(wxHtmlHelpData* data = @NULL); + wxHtmlHelpWindow(wxHtmlHelpData* data = NULL); wxHtmlHelpWindow(wxWindow* parent, int wxWindowID, const wxPoint& pos = wxDefaultPosition, const wxSize& pos = wxDefaultSize, int style = wxTAB_TRAVERSAL|wxBORDER_NONE, int helpStyle = wxHF_DEFAULT_STYLE, - wxHtmlHelpData* data = @NULL); + wxHtmlHelpData* data = NULL); //@} /** You may override this virtual method to add more buttons to the help window's - toolbar. @e toolBar is a pointer to the toolbar and @e style is the style + toolbar. @a toolBar is a pointer to the toolbar and @a style is the style flag as passed to the Create method. - wxToolBar::Realize is called immediately after returning from this function. - See @e samples/html/helpview for an example. */ - virtual void AddToolbarButtons(wxToolBar * toolBar, int style); + virtual void AddToolbarButtons(wxToolBar* toolBar, int style); /** Creates the help window. See @ref wxhtmlhelpwindow() "the constructor" @@ -77,18 +74,16 @@ public: const wxSize& pos = wxDefaultSize, int style = wxTAB_TRAVERSAL|wxBORDER_NONE, int helpStyle = wxHF_DEFAULT_STYLE, - wxHtmlHelpData* data = @NULL); + wxHtmlHelpData* data = NULL); /** Creates contents panel. (May take some time.) - Protected. */ void CreateContents(); /** Creates index panel. (May take some time.) - Protected. */ void CreateIndex(); @@ -103,12 +98,10 @@ public: Displays page x. If not found it will give the user the choice of searching books. Looking for the page runs in these steps: - try to locate file named x (if x is for example "doc/howto.htm") try to open starting page of book x try to find x in contents (if x is for example "How To ...") try to find x in index (if x is for example "How To ...") - The second form takes numeric ID as the parameter. (uses extension to MS format, param name="ID" value=id) */ @@ -148,13 +141,12 @@ public: /** Refresh all panels. This is necessary if a new book was added. - Protected. */ void RefreshLists(); /** - Sets the frame's title format. @e format must contain exactly one "%s" + Sets the frame's title format. @a format must contain exactly one "%s" (it will be replaced by the page title). */ void SetTitleFormat(const wxString& format); diff --git a/interface/html/htmlcell.h b/interface/html/htmlcell.h index a60a1be170..bc23b7929c 100644 --- a/interface/html/htmlcell.h +++ b/interface/html/htmlcell.h @@ -22,20 +22,32 @@ public: Constructor. @param clr - The color - + The color @param flags - Can be one of following: + Can be one of following: + + + + + + + wxHTML_CLR_FOREGROUND + + + - wxHTML_CLR_FOREGROUND + change color of text - change color of text - wxHTML_CLR_BACKGROUND - change background color + wxHTML_CLR_BACKGROUND + + + + + change background color */ wxHtmlColourCell(wxColour clr, int flags = wxHTML_CLR_FOREGROUND); }; @@ -62,14 +74,13 @@ public: Constructor. @param wnd - Connected window. It is parent window must be the wxHtmlWindow object within - which it is displayed! - + Connected window. It is parent window must be the wxHtmlWindow object within + which it is displayed! @param w - Floating width. If non-zero width of wnd window is adjusted so that it is - always w percents of parent container's width. (For example w = 100 means that - the window - will always have same width as parent container) + Floating width. If non-zero width of wnd window is adjusted so that it is + always w percents of parent container's width. (For example w = 100 means + that the window + will always have same width as parent container) */ wxHtmlWidgetCell(wxWindow* wnd, int w = 0); }; @@ -108,31 +119,26 @@ public: should not be crossed by words, images etc.). If this cell cannot be divided into two pieces (each one on another page) then it moves the pagebreak few pixels up. - Returns @true if pagebreak was modified, @false otherwise - Usage: */ - virtual bool AdjustPagebreak(int * pagebreak); + virtual bool AdjustPagebreak(int* pagebreak); /** Renders the cell. @param dc - Device context to which the cell is to be drawn - + Device context to which the cell is to be drawn @param x,y - Coordinates of parent's upper left corner (origin). You must - add this to m_PosX,m_PosY when passing coordinates to dc's methods - Example : dc - DrawText("hello", x + m_PosX, y + m_PosY) - + Coordinates of parent's upper left corner (origin). You must + add this to m_PosX,m_PosY when passing coordinates to dc's methods + Example : dc - DrawText("hello", x + m_PosX, y + m_PosY) @param view_y1 - y-coord of the first line visible in window. This is - used to optimize rendering speed - + y-coord of the first line visible in window. This is + used to optimize rendering speed @param view_y2 - y-coord of the last line visible in window. This is - used to optimize rendering speed + y-coord of the last line visible in window. This is + used to optimize rendering speed */ virtual void Draw(wxDC& dc, int x, int y, int view_y1, int view_y2); @@ -144,12 +150,11 @@ public: or font setter) must be drawn even if they are invisible! @param dc - Device context to which the cell is to be drawn - + Device context to which the cell is to be drawn @param x,y - Coordinates of parent's upper left corner. You must - add this to m_PosX,m_PosY when passing coordinates to dc's methods - Example : dc - DrawText("hello", x + m_PosX, y + m_PosY) + Coordinates of parent's upper left corner. You must + add this to m_PosX,m_PosY when passing coordinates to dc's methods + Example : dc - DrawText("hello", x + m_PosX, y + m_PosY) */ virtual void DrawInvisible(wxDC& dc, int x, int y); @@ -158,16 +163,14 @@ public: following in the list matches), @NULL otherwise. (In other words if you call top-level container's Find it will return pointer to the first cell that matches the condition) - It is recommended way how to obtain pointer to particular cell or to cell of some type (e.g. wxHtmlAnchorCell reacts on wxHTML_COND_ISANCHOR condition) @param condition - Unique integer identifier of condition - + Unique integer identifier of condition @param param - Optional parameters + Optional parameters */ virtual const wxHtmlCell* Find(int condition, const void* param); @@ -181,7 +184,6 @@ public: Returns pointer to the first cell in the list. You can then use child's GetNext() method to obtain pointer to the next cell in list. - @b Note: This shouldn't be used by the end user. If you need some way of finding particular cell in the list, try Find() method instead. @@ -204,9 +206,9 @@ public: (Note: this makes sense only for visible tags). @param x,y - Coordinates of position where the user pressed mouse button. - These coordinates are used e.g. by COLORMAP. Values are relative to the - upper left corner of THIS cell (i.e. from 0 to m_Width or m_Height) + Coordinates of position where the user pressed mouse button. + These coordinates are used e.g. by COLORMAP. Values are relative to the + upper left corner of THIS cell (i.e. from 0 to m_Width or m_Height) */ virtual wxHtmlLinkInfo* GetLink(int x = 0, int y = 0); @@ -214,7 +216,7 @@ public: Returns cursor to show when mouse pointer is over the cell. @param window - interface to the parent HTML window + interface to the parent HTML window */ virtual wxCursor GetMouseCursor(wxHtmlWindowInterface* window); @@ -250,13 +252,11 @@ public: /** This method performs two actions: - adjusts the cell's width according to the fact that maximal possible width is @e w. (this has sense when working with horizontal lines, tables etc.) prepares layout (=fill-in m_PosX, m_PosY (and sometimes m_Height) members) based on actual width @e w - It must be called before displaying cells structure because m_PosX and m_PosY are undefined (or invalid) before calling Layout. @@ -270,13 +270,11 @@ public: wxHtmlWindow::LoadPage. @param window - interface to the parent HTML window - + interface to the parent HTML window @param pos - coordinates of mouse click (this is relative to cell's origin - + coordinates of mouse click (this is relative to cell's origin @param event - mouse event that triggered the call + mouse event that triggered the call @returns @true if a link was clicked, @false otherwise. */ @@ -331,7 +329,7 @@ class wxHtmlContainerCell : public wxHtmlCell { public: /** - Constructor. @e parent is pointer to parent container or @NULL. + Constructor. @a parent is pointer to parent container or @NULL. */ wxHtmlContainerCell(wxHtmlContainerCell parent); @@ -353,17 +351,16 @@ public: wxColour GetBackgroundColour(); /** - Returns the indentation. @e ind is one of the @b wxHTML_INDENT_* constants. - + Returns the indentation. @a ind is one of the @b wxHTML_INDENT_* constants. @b Note: You must call GetIndentUnits() - with same @e ind parameter in order to correctly interpret the returned integer + with same @a ind parameter in order to correctly interpret the returned integer value. It is NOT always in pixels! */ int GetIndent(int ind); /** - Returns the units of indentation for @e ind where @e ind is one + Returns the units of indentation for @a ind where @a ind is one of the @b wxHTML_INDENT_* constants. */ int GetIndentUnits(int ind); @@ -383,30 +380,55 @@ public: /** Sets the container's @e horizontal alignment. During wxHtmlCell::Layout - each line is aligned according to @e al value. + each line is aligned according to @a al value. @param al - new horizontal alignment. May be one of these values: + new horizontal alignment. May be one of these values: + + + + + + + wxHTML_ALIGN_LEFT + + - wxHTML_ALIGN_LEFT + lines are left-aligned (default) - lines are left-aligned (default) - wxHTML_ALIGN_JUSTIFY - lines are justified - wxHTML_ALIGN_CENTER + wxHTML_ALIGN_JUSTIFY - lines are centered - wxHTML_ALIGN_RIGHT + lines are justified - lines are right-aligned + + + + + wxHTML_ALIGN_CENTER + + + + + lines are centered + + + + + + wxHTML_ALIGN_RIGHT + + + + + lines are right-aligned */ void SetAlignHor(int al); @@ -414,22 +436,41 @@ public: Sets the container's @e vertical alignment. This is per-line alignment! @param al - new vertical alignment. May be one of these values: + new vertical alignment. May be one of these values: + + + + + + + wxHTML_ALIGN_BOTTOM + + + + + cells are over the line (default) + + + + + + wxHTML_ALIGN_CENTER + + + + + cells are centered on line - wxHTML_ALIGN_BOTTOM - cells are over the line (default) - wxHTML_ALIGN_CENTER + wxHTML_ALIGN_TOP - cells are centered on line - wxHTML_ALIGN_TOP - cells are under the line + cells are under the line */ void SetAlignVer(int al); @@ -442,10 +483,9 @@ public: Sets the border (frame) colours. A border is a rectangle around the container. @param clr1 - Colour of top and left lines - + Colour of top and left lines @param clr2 - Colour of bottom and right lines + Colour of bottom and right lines */ void SetBorder(const wxColour& clr1, const wxColour& clr2); @@ -453,120 +493,181 @@ public: Sets the indentation (free space between borders of container and subcells). @param i - Indentation value. - + Indentation value. @param what - Determines which of the four borders we're setting. It is OR - combination of following constants: + Determines which of the four borders we're setting. It is OR + combination of following constants: + + + + + + + wxHTML_INDENT_TOP + + + + + top border + + + + + + wxHTML_INDENT_BOTTOM + + + + + bottom + + + + + + wxHTML_INDENT_LEFT + + + + + left + + + + + + wxHTML_INDENT_RIGHT + + - wxHTML_INDENT_TOP + right - top border - wxHTML_INDENT_BOTTOM - bottom - wxHTML_INDENT_LEFT + wxHTML_INDENT_HORIZONTAL - left - wxHTML_INDENT_RIGHT + left and right - right - wxHTML_INDENT_HORIZONTAL - left and right - wxHTML_INDENT_VERTICAL + wxHTML_INDENT_VERTICAL - top and bottom - wxHTML_INDENT_ALL + top and bottom - all 4 borders + + + wxHTML_INDENT_ALL + + + + + all 4 borders @param units - Units of i. This parameter affects interpretation of value. + Units of i. This parameter affects interpretation of value. + + + + + + + wxHTML_UNITS_PIXELS + + + + + i is number of pixels + + - wxHTML_UNITS_PIXELS - i is number of pixels + wxHTML_UNITS_PERCENT - wxHTML_UNITS_PERCENT - i is interpreted as percents of width - of parent container + + i is interpreted as percents of width + of parent container */ void SetIndent(int i, int what, int units = wxHTML_UNITS_PIXELS); /** Sets minimal height of the container. - When container's wxHtmlCell::Layout is called, m_Height is set depending on layout of subcells to the height of area covered by layed-out subcells. Calling this method guarantees you that the height - of container is never smaller than @e h - even if the subcells cover + of container is never smaller than @a h - even if the subcells cover much smaller area. @param h - The minimal height. - + The minimal height. @param align - If height of the container is lower than the minimum height, empty space must - be inserted - somewhere in order to ensure minimal height. This parameter is one of + If height of the container is lower than the minimum height, empty space + must be inserted + somewhere in order to ensure minimal height. This parameter is one of wxHTML_ALIGN_TOP, - wxHTML_ALIGN_BOTTOM, wxHTML_ALIGN_CENTER. It refers to the contents, not to the - empty place. + wxHTML_ALIGN_BOTTOM, wxHTML_ALIGN_CENTER. It refers to the contents, not to + the + empty place. */ void SetMinHeight(int h, int align = wxHTML_ALIGN_TOP); //@{ /** Sets floating width adjustment. - The normal behaviour of container is that its width is the same as the width of parent container (and thus you can have only one sub-container per line). You can change this by setting FWA. - - @e pixel_scale is number of real pixels that equals to 1 HTML pixel. + @a pixel_scale is number of real pixels that equals to 1 HTML pixel. @param w - Width of the container. If the value is negative it means - complement to full width of parent container (e.g. - SetWidthFloat(-50, wxHTML_UNITS_PIXELS) sets the width - of container to parent's width minus 50 pixels. This is useful when - creating tables - you can call SetWidthFloat(50) and SetWidthFloat(-50)) - + Width of the container. If the value is negative it means + complement to full width of parent container (e.g. + SetWidthFloat(-50, wxHTML_UNITS_PIXELS) sets the width + of container to parent's width minus 50 pixels. This is useful when + creating tables - you can call SetWidthFloat(50) and SetWidthFloat(-50)) @param units - Units of w This parameter affects the interpretation of value. + Units of w This parameter affects the interpretation of value. + + + + + + + wxHTML_UNITS_PIXELS + + + + + w is number of pixels + + - wxHTML_UNITS_PIXELS - w is number of pixels + wxHTML_UNITS_PERCENT - wxHTML_UNITS_PERCENT - w is interpreted as percents of width - of parent container + w is interpreted as percents of width + of parent container @param tag - In the second version of method, w and units - info is extracted from tag's WIDTH parameter. + In the second version of method, w and units + info is extracted from tag's WIDTH parameter. */ void SetWidthFloat(int w, int units); void SetWidthFloat(const wxHtmlTag& tag, @@ -605,7 +706,7 @@ public: only within wxHtmlWindow::OnLinkClicked, @NULL otherwise. */ - const wxMouseEvent * GetEvent(); + const wxMouseEvent* GetEvent(); /** Return @e HREF value of the @c A tag. @@ -617,7 +718,7 @@ public: only within wxHtmlWindow::OnLinkClicked, @NULL otherwise. */ - const wxHtmlCell * GetHtmlCell(); + const wxHtmlCell* GetHtmlCell(); /** Return @e TARGET value of the @c A tag (this value diff --git a/interface/html/htmlfilt.h b/interface/html/htmlfilt.h index 46d57a3428..aea59f70bf 100644 --- a/interface/html/htmlfilt.h +++ b/interface/html/htmlfilt.h @@ -29,14 +29,12 @@ public: /** Returns @true if this filter is capable of reading file @e file. - Example: */ bool CanRead(const wxFSFile& file); /** Reads the file and returns string with HTML document. - Example: */ wxString ReadFile(const wxFSFile& file); diff --git a/interface/html/htmlpars.h b/interface/html/htmlpars.h index 509a90bbdc..355e8fcc33 100644 --- a/interface/html/htmlpars.h +++ b/interface/html/htmlpars.h @@ -33,7 +33,7 @@ public: /** This is the core method of each handler. It is called each time - one of supported tags is detected. @e tag contains all necessary + one of supported tags is detected. @a tag contains all necessary info (see wxHtmlTag for details). @returns @true if ParseInner was called, @false otherwise. @@ -43,20 +43,20 @@ public: /** This method calls parser's wxHtmlParser::DoParsing method for the string between this tag and the paired ending tag: - In this example, a call to ParseInner (with @e tag pointing to A tag) + + In this example, a call to ParseInner (with @a tag pointing to A tag) will parse 'Hello, world!'. */ void ParseInner(const wxHtmlTag& tag); /** - Assigns @e parser to this handler. Each @b instance of handler + Assigns @a parser to this handler. Each @b instance of handler is guaranteed to be called only from the parser. */ virtual void SetParser(wxHtmlParser parser); /** @b wxHtmlParser* m_Parser - This attribute is used to access parent parser. It is protected so that it can't be accessed by user but can be accessed from derived classes. */ @@ -102,11 +102,9 @@ public: /** This may (and may not) be overwritten in derived class. - This method is called each time new tag is about to be added. - @e tag contains information about the tag. (See wxHtmlTag + @a tag contains information about the tag. (See wxHtmlTag for details.) - Default (wxHtmlParser) behaviour is this: First it finds a handler capable of handling this tag and then it calls handler's HandleTag method. @@ -117,20 +115,17 @@ public: Adds handler to the internal list ( hash table) of handlers. This method should not be called directly by user but rather by derived class' constructor. - This adds the handler to this @b instance of wxHtmlParser, not to all objects of this class! (Static front-end to AddTagHandler is provided by wxHtmlWinParser). - All handlers are deleted on object deletion. */ virtual void AddTagHandler(wxHtmlTagHandler handler); /** Must be overwritten in derived class. - This method is called by DoParsing() - each time a part of text is parsed. @e txt is NOT only one word, it is + each time a part of text is parsed. @a txt is NOT only one word, it is substring of input. It is not formatted or preprocessed (so white spaces are unmodified). */ @@ -155,13 +150,12 @@ public: reference to it is parent parser it can easily request the file by calling */ -#define wxFileSystem* GetFS() /* implementation is private */ + wxFileSystem* GetFS(); /** Returns product of parsing. Returned value is result of parsing of the document. The type of this result depends on internal representation in derived parser (but it must be derived from wxObject!). - See wxHtmlWinParser for details. */ virtual wxObject* GetProduct(); @@ -172,7 +166,7 @@ public: wxString* GetSource(); /** - Setups the parser for parsing the @e source string. (Should be overridden + Setups the parser for parsing the @a source string. (Should be overridden in derived class) */ virtual void InitParser(const wxString& source); @@ -184,26 +178,44 @@ public: of @e OpenURL in derived class. @param type - Indicates type of the resource. Is one of: + Indicates type of the resource. Is one of: + + + + + + + wxHTML_URL_PAGE + - wxHTML_URL_PAGE - Opening a HTML page. + Opening a HTML page. - wxHTML_URL_IMAGE - Opening an image. - wxHTML_URL_OTHER + wxHTML_URL_IMAGE - Opening a resource that doesn't fall into - any other category. + + + Opening an image. + + + + + + wxHTML_URL_OTHER + + + + + Opening a resource that doesn't fall into + any other category. @param url - URL being opened. + URL being opened. */ virtual wxFSFile* OpenURL(wxHtmlURLType type, const wxString& url); @@ -211,15 +223,12 @@ public: /** Proceeds parsing of the document. This is end-user method. You can simply call it when you need to obtain parsed output (which is parser-specific) - The method does these things: - calls @ref initparser() InitParser(source) calls DoParsing() calls GetProduct() calls DoneParser() returns value returned by GetProduct - You shouldn't use InitParser, DoParsing, GetProduct or DoneParser directly. */ wxObject* Parse(const wxString& source); @@ -236,11 +245,10 @@ public: The handler should already be added to this parser. @param handler - the handler - + the handler @param tags - List of tags (in same format as GetSupportedTags's return value). The parser - will redirect these tags to handler (until call to PopTagHandler). + List of tags (in same format as GetSupportedTags's return value). The parser + will redirect these tags to handler (until call to PopTagHandler). */ void PushTagHandler(wxHtmlTagHandler* handler, const wxString& tags); @@ -250,7 +258,7 @@ public: files. (For example @c IMG tag handler requests wxFSFile with the image data.) */ -#define void SetFS(wxFileSystem fs) /* implementation is private */ + void SetFS(wxFileSystem fs); /** Call this function to interrupt parsing from a tag handler. No more tags diff --git a/interface/html/htmltag.h b/interface/html/htmltag.h index c1ae90495a..a54ef932d1 100644 --- a/interface/html/htmltag.h +++ b/interface/html/htmltag.h @@ -24,13 +24,12 @@ public: yourself. Feel free to ignore the constructor parameters. Have a look at src/html/htmlpars.cpp if you're interested in creating it. */ - wxHtmlTag(wxHtmlTag * parent, const wxString& source, int pos, + wxHtmlTag(wxHtmlTag* parent, const wxString& source, int pos, int end_pos, wxHtmlTagsCache* cache, - wxHtmlEntitiesParser * entParser); + wxHtmlEntitiesParser* entParser); /** Returns a string containing all parameters. - Example : tag contains @c FONT SIZE=+2 COLOR="#000000". Call to tag.GetAllParams() would return @c SIZE=+2 COLOR="#000000". */ @@ -69,35 +68,32 @@ public: parameter exists or not (use wxHtmlTag::HasParam) first. @param par - The parameter's name. - + The parameter's name. @param with_quotes - @true if you want to get quotes as well. See example. + @true if you want to get quotes as well. See example. */ - wxString GetParam(const wxString& par, bool with_quotes = @false); + wxString GetParam(const wxString& par, bool with_quotes = false); /** - Interprets tag parameter @e par as colour specification and saves its value + Interprets tag parameter @a par as colour specification and saves its value into wxColour variable pointed by @e clr. - - Returns @true on success and @false if @e par is not colour specification or + Returns @true on success and @false if @a par is not colour specification or if the tag has no such parameter. */ - bool GetParamAsColour(const wxString& par, wxColour * clr); + bool GetParamAsColour(const wxString& par, wxColour* clr); /** - Interprets tag parameter @e par as an integer and saves its value + Interprets tag parameter @a par as an integer and saves its value into int variable pointed by @e value. - - Returns @true on success and @false if @e par is not an integer or + Returns @true on success and @false if @a par is not an integer or if the tag has no such parameter. */ - bool GetParamAsInt(const wxString& par, int * value); + bool GetParamAsInt(const wxString& par, int* value); /** Returns @true if this tag is paired with ending tag, @false otherwise. - See the example of HTML document: + In this example tags HTML and BODY have ending tags, first P and BR doesn't have ending tag while the second P has. The third P tag (which is ending itself) of course doesn't have ending tag. @@ -110,7 +106,7 @@ public: "SIZE" and "COLOR". @param par - the parameter you're looking for. + the parameter you're looking for. */ bool HasParam(const wxString& par); @@ -122,14 +118,12 @@ public: in @e format). @param par - The name of the tag you want to query - + The name of the tag you want to query @param format - scanf()-like format string. - + scanf()-like format string. @param value - pointer to a variable to store the value in + pointer to a variable to store the value in */ - wxString ScanParam(const wxString& par, const wxChar * format, - void * value); + wxString ScanParam(const wxString& par, const wxChar* format, + void* value); }; diff --git a/interface/html/htmlwin.h b/interface/html/htmlwin.h index 7f6dfeee44..e25de19524 100644 --- a/interface/html/htmlwin.h +++ b/interface/html/htmlwin.h @@ -48,7 +48,7 @@ public: constructor. @param style - Window style. See wxHtmlWindow. + Window style. See wxHtmlWindow. */ wxHtmlWindow(); wxHtmlWindow(wxWindow parent, wxWindowID id = -1, @@ -61,7 +61,6 @@ public: /** Adds @ref overview_filters "input filter" to the static list of available filters. These filters are present by default: - @c text/html MIME type @c image/* MIME types Plain Text filter (this filter is used if no other filter matches) @@ -72,7 +71,7 @@ public: Appends HTML fragment to currently displayed text and refreshes the window. @param source - HTML code fragment + HTML code fragment @returns @false if an error occurred, @true otherwise. */ @@ -80,9 +79,8 @@ public: /** Returns pointer to the top-level container. - See also: @ref overview_cells "Cells Overview", - @ref overview_printing "Printing Overview" + @ref overview_printing */ wxHtmlContainerCell* GetInternalRepresentation(); @@ -145,43 +143,39 @@ public: @returns @false if an error occurred, @true otherwise - @sa LoadPage() + @see LoadPage() */ virtual bool LoadFile(const wxFileName& filename); /** - Unlike SetPage this function first loads HTML page from @e location + Unlike SetPage this function first loads HTML page from @a location and then displays it. See example: @param location - The address of document. See wxFileSystem for details on address format and + The address of document. See wxFileSystem for details on address format and behaviour of "opener". @returns @false if an error occurred, @true otherwise - @sa LoadFile() + @see LoadFile() */ virtual bool LoadPage(const wxString& location); /** This method is called when a mouse button is clicked inside wxHtmlWindow. - The default behaviour is to emit a wxHtmlCellEvent and, if the event was not processed or skipped, call OnLinkClicked() if the cell contains an hypertext link. - Overloading this method is deprecated; intercept the event instead. @param cell - The cell inside which the mouse was clicked, always a simple - (i.e. non-container) cell - + The cell inside which the mouse was clicked, always a simple + (i.e. non-container) cell @param x, y - The logical coordinates of the click point - + The logical coordinates of the click point @param event - The mouse event containing other information about the click + The mouse event containing other information about the click @returns @true if a link was clicked, @false otherwise. */ @@ -194,11 +188,10 @@ public: Overloading this method is deprecated; intercept the event instead. @param cell - The cell inside which the mouse is currently, always a simple - (i.e. non-container) cell - + The cell inside which the mouse is currently, always a simple + (i.e. non-container) cell @param x, y - The logical coordinates of the click point + The logical coordinates of the click point */ virtual void OnCellMouseHover(wxHtmlCell cell, wxCoord x, wxCoord y); @@ -208,7 +201,6 @@ public: wxHtmlLinkEvent and, if the event was not processed or skipped, call LoadPage() and do nothing else. Overloading this method is deprecated; intercept the event instead. - Also see wxHtmlLinkInfo. */ virtual void OnLinkClicked(const wxHtmlLinkInfo& link); @@ -223,35 +215,51 @@ public: behaviour is to always return @c wxHTML_OPEN. @param type - Indicates type of the resource. Is one of + Indicates type of the resource. Is one of - wxHTML_URL_PAGE - Opening a HTML page. - wxHTML_URL_IMAGE + wxHTML_URL_PAGE - Opening an image. - wxHTML_URL_OTHER - Opening a resource that doesn't fall into - any other category. + Opening a HTML page. - @param url - URL being opened. + + + + wxHTML_URL_IMAGE + + + + + Opening an image. + + + + + + wxHTML_URL_OTHER + + + + + Opening a resource that doesn't fall into + any other category. + @param url + URL being opened. @param redirect - Pointer to wxString variable that must be filled with an - URL if OnOpeningURL returns wxHTML_REDIRECT. + Pointer to wxString variable that must be filled with an + URL if OnOpeningURL returns wxHTML_REDIRECT. */ virtual wxHtmlOpeningStatus OnOpeningURL(wxHtmlURLType type, const wxString& url, - wxString * redirect); + wxString* redirect); /** Called on parsing @c TITLE tag. @@ -262,14 +270,12 @@ public: This reads custom settings from wxConfig. It uses the path 'path' if given, otherwise it saves info into currently selected path. The values are stored in sub-path @c wxHtmlWindow - Read values: all things set by SetFonts, SetBorders. @param cfg - wxConfig from which you want to read the configuration. - + wxConfig from which you want to read the configuration. @param path - Optional path in config tree. If not given current path is used. + Optional path in config tree. If not given current path is used. */ virtual void ReadCustomization(wxConfigBase cfg, wxString path = wxEmptyString); @@ -277,17 +283,17 @@ public: /** Selects all text in the window. - @sa SelectLine(), SelectWord() + @see SelectLine(), SelectWord() */ void SelectAll(); /** - Selects the line of text that @e pos points at. Note that @e pos + Selects the line of text that @a pos points at. Note that @e pos is relative to the top of displayed page, not to window's origin, use wxScrolledWindow::CalcUnscrolledPosition to convert physical coordinate. - @sa SelectAll(), SelectWord() + @see SelectAll(), SelectWord() */ void SelectLine(const wxPoint& pos); @@ -297,7 +303,7 @@ public: wxScrolledWindow::CalcUnscrolledPosition to convert physical coordinate. - @sa SelectAll(), SelectLine() + @see SelectAll(), SelectLine() */ void SelectWord(const wxPoint& pos); @@ -312,7 +318,7 @@ public: image: @param b - indentation from borders in pixels + indentation from borders in pixels */ void SetBorders(int b); @@ -320,39 +326,38 @@ public: This function sets font sizes and faces. @param normal_face - This is face name for normal (i.e. non-fixed) font. - It can be either empty string (then the default face is chosen) or - platform-specific face name. Examples are "helvetica" under Unix or - "Times New Roman" under Windows. - + This is face name for normal (i.e. non-fixed) font. + It can be either empty string (then the default face is chosen) or + platform-specific face name. Examples are "helvetica" under Unix or + "Times New Roman" under Windows. @param fixed_face - The same thing for fixed face ( TT../TT ) - + The same thing for fixed face ( TT../TT ) @param sizes - This is an array of 7 items of int type. - The values represent size of font with HTML size from -2 to +4 - ( FONT SIZE=-2 to FONT SIZE=+4 ). Default sizes are used if sizes - is @NULL. + This is an array of 7 items of int type. + The values represent size of font with HTML size from -2 to +4 + ( FONT SIZE=-2 to FONT SIZE=+4 ). Default sizes are used if sizes + is @NULL. */ void SetFonts(const wxString& normal_face, const wxString& fixed_face, - const int sizes = @NULL); + const int sizes = NULL); /** Sets HTML page and display it. This won't @b load the page!! It will display the @e source. See example: + If you want to load a document from some location use LoadPage() instead. @param source - The HTML document source to be displayed. + The HTML document source to be displayed. @returns @false if an error occurred, @true otherwise. */ bool SetPage(const wxString& source); /** - Sets the frame in which page title will be displayed. @e format is format of + Sets the frame in which page title will be displayed. @a format is format of frame title, e.g. "HtmlHelp : %s". It must contain exactly one %s. This %s is substituted with HTML page title. */ @@ -364,7 +369,7 @@ public: (Default is -1 = no messages.) @param bar - statusbar slot number (0..n) + statusbar slot number (0..n) */ void SetRelatedStatusBar(int bar); @@ -378,14 +383,12 @@ public: if given, otherwise it saves info into currently selected path. Regardless of whether the path is given or not, the function creates sub-path @c wxHtmlWindow. - Saved values: all things set by SetFonts, SetBorders. @param cfg - wxConfig to which you want to save the configuration. - + wxConfig to which you want to save the configuration. @param path - Optional path in config tree. If not given, the current path is used. + Optional path in config tree. If not given, the current path is used. */ virtual void WriteCustomization(wxConfigBase cfg, wxString path = wxEmptyString); @@ -407,7 +410,7 @@ public: /** The constructor is not normally used by the user code. */ - wxHyperlinkEvent(int id, const wxHtmlLinkInfo & linkinfo); + wxHyperlinkEvent(int id, const wxHtmlLinkInfo& linkinfo); /** Returns the wxHtmlLinkInfo which contains info about the cell clicked and the @@ -433,13 +436,13 @@ public: The constructor is not normally used by the user code. */ wxHtmlCellEvent(wxEventType commandType, int id, - wxHtmlCell * cell, - const wxPoint & point); + wxHtmlCell* cell, + const wxPoint& point); /** Returns the wxHtmlCellEvent associated with the event. */ - wxHtmlCell * GetCell(); + wxHtmlCell* GetCell(); /** Returns @true if @ref setlinkclicked() SetLinkClicked(@true) has previously diff --git a/interface/html/htmprint.h b/interface/html/htmprint.h index 07c6476c89..4d5c3c8215 100644 --- a/interface/html/htmprint.h +++ b/interface/html/htmprint.h @@ -39,56 +39,50 @@ public: Renders HTML text to the DC. @param x,y - position of upper-left corner of printing rectangle (see SetSize) - + position of upper-left corner of printing rectangle (see SetSize) @param from - y-coordinate of the very first visible cell - + y-coordinate of the very first visible cell @param dont_render - if @true then this method only returns y coordinate of the next page - and does not output anything + if @true then this method only returns y coordinate of the next page + and does not output anything */ - int Render(int x, int y, int from = 0, int dont_render = @false); + int Render(int x, int y, int from = 0, int dont_render = false); /** Assign DC instance to the renderer. - - @e pixel_scale can be used when rendering to high-resolution DCs (e.g. printer) + @a pixel_scale can be used when rendering to high-resolution DCs (e.g. printer) to adjust size of pixel metrics. (Many dimensions in HTML are given in pixels -- e.g. image sizes. 300x300 image would be only one inch wide on typical printer. With pixel_scale = 3.0 it would be 3 inches.) */ -#define void SetDC(wxDC* dc, double pixel_scale = 1.0) /* implementation is private */ + void SetDC(wxDC* dc, double pixel_scale = 1.0); /** Sets fonts. See wxHtmlWindow::SetFonts for detailed description. - See also SetSize(). */ void SetFonts(const wxString& normal_face, const wxString& fixed_face, - const int sizes = @NULL); + const int sizes = NULL); /** Assign text to the renderer. Render() then draws the text onto DC. @param html - HTML text. This is not a filename. - + HTML text. This is not a filename. @param basepath - base directory (html string would be stored there if it was in - file). It is used to determine path for loading images, for example. - + base directory (html string would be stored there if it was in + file). It is used to determine path for loading images, for example. @param isdir - @false if basepath is filename, @true if it is directory name - (see wxFileSystem for detailed explanation) + @false if basepath is filename, @true if it is directory name + (see wxFileSystem for detailed explanation) */ void SetHtmlText(const wxString& html, const wxString& basepath = wxEmptyString, - bool isdir = @true); + bool isdir = true); /** Set size of output rectangle, in pixels. Note that you @b can't change @@ -117,14 +111,13 @@ public: Constructor. @param name - Name of the printing object. Used by preview frames and setup dialogs. - + Name of the printing object. Used by preview frames and setup dialogs. @param parentWindow - pointer to the window that will own the preview frame and setup dialogs. May be - @NULL. + pointer to the window that will own the preview frame and setup dialogs. + May be @NULL. */ wxHtmlEasyPrinting(const wxString& name = "Printing", - wxWindow* parentWindow = @NULL); + wxWindow* parentWindow = NULL); /** Returns a pointer to wxPageSetupDialogData instance used by @@ -150,7 +143,6 @@ public: /** Preview HTML file. - Returns @false in case of error -- call wxPrinter::GetLastError to get detailed information about the kind of the error. @@ -159,24 +151,21 @@ public: /** Preview HTML text (not file!). - Returns @false in case of error -- call wxPrinter::GetLastError to get detailed information about the kind of the error. @param htmltext - HTML text. - + HTML text. @param basepath - base directory (html string would be stored there if it was in - file). It is used to determine path for loading images, for example. + base directory (html string would be stored there if it was in + file). It is used to determine path for loading images, for example. */ bool PreviewText(const wxString& htmltext, const wxString& basepath = wxEmptyString); /** Print HTML file. - Returns @false in case of error -- call wxPrinter::GetLastError to get detailed information about the kind of the error. @@ -185,17 +174,15 @@ public: /** Print HTML text (not file!). - Returns @false in case of error -- call wxPrinter::GetLastError to get detailed information about the kind of the error. @param htmltext - HTML text. - + HTML text. @param basepath - base directory (html string would be stored there if it was in - file). It is used to determine path for loading images, for example. + base directory (html string would be stored there if it was in + file). It is used to determine path for loading images, for example. */ bool PrintText(const wxString& htmltext, const wxString& basepath = wxEmptyString); @@ -206,11 +193,10 @@ public: */ void SetFonts(const wxString& normal_face, const wxString& fixed_face, - const int sizes = @NULL); + const int sizes = NULL); /** Set page footer. The following macros can be used inside it: - @DATE@ is replaced by the current date in default format @PAGENUM@ is replaced by page number @PAGESCNT@ is replaced by total number of pages @@ -218,16 +204,14 @@ public: @TITLE@ is replaced with the title of the document @param footer - HTML text to be used as footer. - + HTML text to be used as footer. @param pg - one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants. + one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants. */ void SetFooter(const wxString& footer, int pg = wxPAGE_ALL); /** Set page header. The following macros can be used inside it: - @DATE@ is replaced by the current date in default format @PAGENUM@ is replaced by page number @PAGESCNT@ is replaced by total number of pages @@ -235,10 +219,9 @@ public: @TITLE@ is replaced with the title of the document @param header - HTML text to be used as header. - + HTML text to be used as header. @param pg - one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants. + one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants. */ void SetHeader(const wxString& header, int pg = wxPAGE_ALL); @@ -279,11 +262,10 @@ public: */ void SetFonts(const wxString& normal_face, const wxString& fixed_face, - const int sizes = @NULL); + const int sizes = NULL); /** Set page footer. The following macros can be used inside it: - @DATE@ is replaced by the current date in default format @PAGENUM@ is replaced by page number @PAGESCNT@ is replaced by total number of pages @@ -291,16 +273,14 @@ public: @TITLE@ is replaced with the title of the document @param footer - HTML text to be used as footer. - + HTML text to be used as footer. @param pg - one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants. + one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants. */ void SetFooter(const wxString& footer, int pg = wxPAGE_ALL); /** Set page header. The following macros can be used inside it: - @DATE@ is replaced by the current date in default format @PAGENUM@ is replaced by page number @PAGESCNT@ is replaced by total number of pages @@ -308,10 +288,9 @@ public: @TITLE@ is replaced with the title of the document @param header - HTML text to be used as header. - + HTML text to be used as header. @param pg - one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants. + one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants. */ void SetHeader(const wxString& header, int pg = wxPAGE_ALL); @@ -325,19 +304,17 @@ public: Prepare the class for printing this HTML text. @param html - HTML text. (NOT file!) - + HTML text. (NOT file!) @param basepath - base directory (html string would be stored there if it was in - file). It is used to determine path for loading images, for example. - + base directory (html string would be stored there if it was in + file). It is used to determine path for loading images, for example. @param isdir - @false if basepath is filename, @true if it is directory name - (see wxFileSystem for detailed explanation) + @false if basepath is filename, @true if it is directory name + (see wxFileSystem for detailed explanation) */ void SetHtmlText(const wxString& html, const wxString& basepath = wxEmptyString, - bool isdir = @true); + bool isdir = true); /** Sets margins in millimeters. Defaults to 1 inch for margins and 0.5cm for space diff --git a/interface/html/winpars.h b/interface/html/winpars.h index e18a0f90e2..51ffa9bd61 100644 --- a/interface/html/winpars.h +++ b/interface/html/winpars.h @@ -26,10 +26,11 @@ public: /** You must override this method. In most common case its body consists only of lines of the following type: + I recommend using the @b TAGS_MODULE_* macros. @param parser - Pointer to the parser that requested tables filling. + Pointer to the parser that requested tables filling. */ virtual void FillHandlersTable(wxHtmlWinParser parser); }; @@ -52,7 +53,6 @@ class wxHtmlWinTagHandler : public wxHtmlTagHandler public: /** @b wxHtmlWinParser* m_WParser - Value of this attribute is identical to value of m_Parser. The only different is that m_WParser points to wxHtmlWinParser object while m_Parser points to wxHtmlParser object. (The same object, but overcast.) @@ -81,7 +81,7 @@ public: //@{ /** Constructor. Don't use the default one, use constructor with - @e wndIface parameter (@e wndIface is a pointer to interface object for + @a wndIface parameter (@a wndIface is a pointer to interface object for the associated wxHtmlWindow or other HTML rendering window such as wxHtmlListBox). */ @@ -125,7 +125,6 @@ public: /** Returns (average) char height in standard font. It is used as DC-independent metrics. - @b Note: This function doesn't return the @e actual height. If you want to know the height of the current font, call @c GetDC - GetCharHeight(). */ @@ -134,7 +133,6 @@ public: /** Returns average char width in standard font. It is used as DC-independent metrics. - @b Note: This function doesn't return the @e actual width. If you want to know the height of the current font, call @c GetDC - GetCharWidth() */ @@ -149,14 +147,14 @@ public: /** Returns pointer to the DC used during parsing. */ -#define wxDC* GetDC() /* implementation is private */ + wxDC* GetDC(); /** Returns wxEncodingConverter class used to do conversion between @ref getinputencoding() "input encoding" and @ref getoutputencoding() "output encoding". */ - wxEncodingConverter * GetEncodingConverter(); + wxEncodingConverter* GetEncodingConverter(); /** Returns @true if actual font is bold, @false otherwise. @@ -242,19 +240,19 @@ public: should use OpenContainer wherever possible. */ - wxHtmlContainerCell* SetContainer(wxHtmlContainerCell * c); + wxHtmlContainerCell* SetContainer(wxHtmlContainerCell* c); /** Sets the DC. This must be called before wxHtmlParser::Parse! - @e pixel_scale can be used when rendering to high-resolution + @a pixel_scale can be used when rendering to high-resolution DCs (e.g. printer) to adjust size of pixel metrics. (Many dimensions in HTML are given in pixels -- e.g. image sizes. 300x300 image would be only one inch wide on typical printer. With pixel_scale = 3.0 it would be 3 inches.) */ -#define virtual void SetDC(wxDC dc, double pixel_scale = 1.0) /* implementation is private */ + virtual void SetDC(wxDC dc, double pixel_scale = 1.0); /** - Sets bold flag of actualfont. @e x is either @true of @false. + Sets bold flag of actualfont. @a x is either @true of @false. */ void SetFontBold(int x); @@ -266,12 +264,12 @@ public: void SetFontFace(const wxString& face); /** - Sets fixed face flag of actualfont. @e x is either @true of @false. + Sets fixed face flag of actualfont. @a x is either @true of @false. */ void SetFontFixed(int x); /** - Sets italic flag of actualfont. @e x is either @true of @false. + Sets italic flag of actualfont. @a x is either @true of @false. */ void SetFontItalic(int x); @@ -281,7 +279,7 @@ public: void SetFontSize(int s); /** - Sets underlined flag of actualfont. @e x is either @true of @false. + Sets underlined flag of actualfont. @a x is either @true of @false. */ void SetFontUnderlined(int x); @@ -291,7 +289,7 @@ public: */ void SetFonts(const wxString& normal_face, const wxString& fixed_face, - const int sizes = @NULL); + const int sizes = NULL); /** Sets input encoding. The parser uses this information to build conversion diff --git a/interface/htmllbox.h b/interface/htmllbox.h index 494e86605f..0f99800605 100644 --- a/interface/htmllbox.h +++ b/interface/htmllbox.h @@ -48,10 +48,8 @@ public: Creates the control and optionally sets the initial number of items in it (it may also be set or changed later with wxVListBox::SetItemCount). - There are no special styles defined for wxHtmlListBox, in particular the wxListBox styles (with the exception of @c wxLB_MULTIPLE) can not be used here. - Returns @true on success or @false if the control couldn't be created */ bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, @@ -76,25 +74,24 @@ public: This virtual function may be overridden to change the appearance of the background of the selected cells in the same way as GetSelectedTextColour(). - It should be rarely, if ever, used because wxVListBox::SetSelectionBackground allows to change the selection background for all cells at once and doing anything more fancy is probably going to look strangely. - @sa GetSelectedTextColour() + @see GetSelectedTextColour() */ wxColour GetSelectedTextBgColour(const wxColour& colBg); /** This virtual function may be overridden to customize the appearance of the - selected cells. It is used to determine how the colour @e colFg is going to + selected cells. It is used to determine how the colour @a colFg is going to look inside selection. By default all original colours are completely ignored and the standard, system-dependent, selection colour is used but the program may wish to override this to achieve some custom appearance. - @sa GetSelectedTextBgColour(), - wxVListBox::SetSelectionBackground, wxSystemSettings::GetColour + @see GetSelectedTextBgColour(), + wxVListBox::SetSelectionBackground, wxSystemSettings::GetColour */ wxColour GetSelectedTextColour(const wxColour& colFg); @@ -102,8 +99,7 @@ public: This method must be implemented in the derived class and should return the body (i.e. without @c html nor @c body tags) of the HTML fragment for the given item. - - Note that this function should always return a text fragment for the @e n item + Note that this function should always return a text fragment for the @a n item which renders with the same height both when it is selected and when it's not: i.e. if you call, inside your OnGetItem() implementation, @c IsSelected(n) to make the items appear differently when they are selected, then you should make @@ -124,12 +120,11 @@ public: Overloading this method is deprecated; intercept the event instead. @param n - Index of the item containing the link. - + Index of the item containing the link. @param link - Description of the link. + Description of the link. - @sa See also wxHtmlLinkInfo. + @see See also wxHtmlLinkInfo. */ virtual void OnLinkClicked(size_t n, const wxHtmlLinkInfo& link); }; @@ -199,7 +194,7 @@ public: const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, int n = 0, - const wxString choices[] = @NULL, + const wxString choices[] = NULL, long style = wxHLB_DEFAULT_STYLE, const wxValidator& validator = wxDefaultValidator, const wxString& name = "simpleHtmlListBox"); @@ -230,7 +225,7 @@ public: const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, int n, - const wxString choices[] = @NULL, + const wxString choices[] = NULL, long style = wxHLB_DEFAULT_STYLE, const wxValidator& validator = wxDefaultValidator, const wxString& name = "simpleHtmlListBox"); diff --git a/interface/hyperlink.h b/interface/hyperlink.h index 0e7b171f38..3422349997 100644 --- a/interface/hyperlink.h +++ b/interface/hyperlink.h @@ -22,18 +22,18 @@ public: /** The constructor is not normally used by the user code. */ - wxHyperlinkEvent(wxObject * generator, int id, - const wxString & url); + wxHyperlinkEvent(wxObject* generator, int id, + const wxString& url); /** Returns the URL of the hyperlink where the user has just clicked. */ -#define wxString GetURL() /* implementation is private */ + wxString GetURL(); /** Sets the URL associated with the event. */ -#define void SetURL(const wxString & url) /* implementation is private */ + void SetURL(const wxString& url); }; @@ -83,36 +83,28 @@ public: Creates the hyperlink control. @param parent - Parent window. Must not be @NULL. - + Parent window. Must not be @NULL. @param id - Window identifier. A value of wxID_ANY indicates a default value. - + Window identifier. A value of wxID_ANY indicates a default value. @param label - The label of the hyperlink. - + The label of the hyperlink. @param url - The URL associated with the given label. - + The URL associated with the given label. @param pos - Window position. - + Window position. @param size - Window size. If the wxDefaultSize is specified then the window is sized - appropriately. - + Window size. If the wxDefaultSize is specified then the window is sized + appropriately. @param style - Window style. See wxHyperlinkCtrl. - + Window style. See wxHyperlinkCtrl. @param validator - Window validator. - + Window validator. @param name - Window name. + Window name. */ bool Create(wxWindow* parent, wxWindowID id, - const wxString & label, - const wxString & url, + const wxString& label, + const wxString& url, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style, @@ -134,7 +126,7 @@ public: /** Returns the URL associated with the hyperlink. */ -#define wxString GetURL() /* implementation is private */ + wxString GetURL(); /** Returns @true if the hyperlink has already been clicked by the user at least @@ -154,38 +146,38 @@ public: Sets the colour used to print the label of the hyperlink when the mouse is over the control. */ - void SetHoverColour(const wxColour & colour); + void SetHoverColour(const wxColour& colour); /** Sets the colour used to print the label when the link has never been clicked before (i.e. the link has not been @e visited) and the mouse is not over the control. */ - void SetNormalColour(const wxColour & colour); + void SetNormalColour(const wxColour& colour); /** Sets the URL associated with the hyperlink. */ -#define void SetURL(const wxString & url) /* implementation is private */ + void SetURL(const wxString& url); /** Marks the hyperlink as visited (see wxHyperlinkCtrl::SetVisitedColour). */ - void SetVisited(bool visited = @true); + void SetVisited(bool visited = true); /** Sets the colour used to print the label when the mouse is not over the control and the link has already been clicked before (i.e. the link has been @e visited). */ - void SetVisitedColour(const wxColour & colour); + void SetVisitedColour(const wxColour& colour); /** Constructor. See Create() for more info. */ wxHyperLink(wxWindow* parent, wxWindowID id, - const wxString & label, - const wxString & url, + const wxString& label, + const wxString& url, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style, diff --git a/interface/icon.h b/interface/icon.h index b7f071603d..3ce78124b1 100644 --- a/interface/icon.h +++ b/interface/icon.h @@ -40,78 +40,108 @@ public: Loads an icon from the specified location. @param bits - Specifies an array of pixel values. - + Specifies an array of pixel values. @param width - Specifies the width of the icon. - + Specifies the width of the icon. @param height - Specifies the height of the icon. - + Specifies the height of the icon. @param desiredWidth - Specifies the desired width of the icon. This - parameter only has an effect in Windows (32-bit) where icon resources can + Specifies the desired width of the icon. This + parameter only has an effect in Windows (32-bit) where icon resources can contain - several icons of different sizes. - + several icons of different sizes. @param desiredWidth - Specifies the desired height of the icon. This - parameter only has an effect in Windows (32-bit) where icon resources can + Specifies the desired height of the icon. This + parameter only has an effect in Windows (32-bit) where icon resources can contain - several icons of different sizes. - + several icons of different sizes. @param depth - Specifies the depth of the icon. If this is omitted, the display depth of the - screen is used. - + Specifies the depth of the icon. If this is omitted, the display depth of + the + screen is used. @param name - This can refer to a resource name under MS Windows, or a filename under MS + This can refer to a resource name under MS Windows, or a filename under MS Windows and X. - Its meaning is determined by the flags parameter. - + Its meaning is determined by the flags parameter. @param loc - The object describing the location of the native icon, see - wxIconLocation. - + The object describing the location of the native icon, see + wxIconLocation. @param type - May be one of the following: + May be one of the following: + + + + + + + + wxBITMAP_TYPE_ICO + + + + + Load a Windows icon file. + + + + + + wxBITMAP_TYPE_ICO_RESOURCE + + + + + Load a Windows icon from the resource database. + + + + + + wxBITMAP_TYPE_GIF + + + + + Load a GIF bitmap file. + + + + + wxBITMAP_TYPE_XBM - wxBITMAP_TYPE_ICO - Load a Windows icon file. - wxBITMAP_TYPE_ICO_RESOURCE + Load an X bitmap file. - Load a Windows icon from the resource database. - wxBITMAP_TYPE_GIF - Load a GIF bitmap file. + wxBITMAP_TYPE_XPM - wxBITMAP_TYPE_XBM - Load an X bitmap file. - wxBITMAP_TYPE_XPM + Load an XPM bitmap file. - Load an XPM bitmap file. - The validity of these flags depends on the platform and wxWidgets configuration. - If all possible wxWidgets settings are used, the Windows platform supports ICO - file, ICO resource, - XPM data, and XPM file. Under wxGTK, the available formats are BMP file, XPM - data, XPM file, and PNG file. - Under wxMotif, the available formats are XBM data, XBM file, XPM data, XPM file. + + + The validity of these flags depends on the platform and wxWidgets + configuration. + If all possible wxWidgets settings are used, the Windows platform supports + ICO file, ICO resource, + XPM data, and XPM file. Under wxGTK, the available formats are BMP file, + XPM data, XPM file, and PNG file. + Under wxMotif, the available formats are XBM data, XBM file, XPM data, XPM + file. @remarks The first form constructs an icon object with no data; an - assignment or another member function such as Create - or LoadFile must be called subsequently. + assignment or another member function such as Create or + LoadFile must be called subsequently. */ wxIcon(); wxIcon(const wxIcon& icon); @@ -131,17 +161,16 @@ public: Destructor. See @ref overview_refcountdestruct "reference-counted object destruction" for more info. - If the application omits to delete the icon explicitly, the icon will be destroyed automatically by wxWidgets when the application exits. - Do not delete an icon that is selected into a memory device context. */ ~wxIcon(); /** - Copies @e bmp bitmap to this icon. Under MS Windows the bitmap + Copies @a bmp bitmap to this icon. Under MS Windows the bitmap must have mask colour set. + LoadFile() Wx::Icon-new( width, height, depth = -1 ) @@ -165,56 +194,91 @@ public: /** Gets the width of the icon in pixels. - @sa GetHeight() + @see GetHeight() */ int GetWidth(); /** Returns @true if icon data is present. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** Loads an icon from a file or resource. @param name - Either a filename or a Windows resource name. - The meaning of name is determined by the type parameter. - + Either a filename or a Windows resource name. + The meaning of name is determined by the type parameter. @param type - One of the following values: + One of the following values: + + + + + + + + wxBITMAP_TYPE_ICO + + + + + Load a Windows icon file. + + + + + + wxBITMAP_TYPE_ICO_RESOURCE + + + + + Load a Windows icon from the resource database. + + + + + + wxBITMAP_TYPE_GIF + + + + + Load a GIF bitmap file. + + + + + + wxBITMAP_TYPE_XBM + - wxBITMAP_TYPE_ICO + Load an X bitmap file. - Load a Windows icon file. - wxBITMAP_TYPE_ICO_RESOURCE - Load a Windows icon from the resource database. - wxBITMAP_TYPE_GIF + wxBITMAP_TYPE_XPM - Load a GIF bitmap file. - wxBITMAP_TYPE_XBM + Load an XPM bitmap file. - Load an X bitmap file. - wxBITMAP_TYPE_XPM - Load an XPM bitmap file. - The validity of these flags depends on the platform and wxWidgets configuration. + The validity of these flags depends on the platform and wxWidgets + configuration. @returns @true if the operation succeeded, @false otherwise. - @sa wxIcon() + @see wxIcon() */ bool LoadFile(const wxString& name, wxBitmapType type); @@ -222,7 +286,7 @@ public: Sets the depth member (does not affect the icon data). @param depth - Icon depth. + Icon depth. */ void SetDepth(int depth); @@ -230,7 +294,7 @@ public: Sets the height member (does not affect the icon data). @param height - Icon height in pixels. + Icon height in pixels. */ void SetHeight(int height); @@ -238,7 +302,7 @@ public: Sets the width member (does not affect the icon data). @param width - Icon width in pixels. + Icon width in pixels. */ void SetWidth(int width); @@ -246,7 +310,7 @@ public: Assignment operator, using @ref overview_trefcount "reference counting". @param icon - Icon to assign. + Icon to assign. */ wxIcon operator =(const wxIcon& icon); }; diff --git a/interface/iconloc.h b/interface/iconloc.h index 4629ed4f13..f4c06ee65d 100644 --- a/interface/iconloc.h +++ b/interface/iconloc.h @@ -35,5 +35,5 @@ public: Returns @true if the object is valid, i.e. was properly initialized, and @false otherwise. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); }; diff --git a/interface/image.h b/interface/image.h index 88b0d81d98..100ca29830 100644 --- a/interface/image.h +++ b/interface/image.h @@ -50,11 +50,11 @@ public: available images. @param stream - Opened input stream for reading image data. Currently, the stream must support - seeking. + Opened input stream for reading image data. Currently, the stream must + support seeking. @returns Number of available images. For most image handlers, this is 1 - (exceptions are TIFF and ICO formats). + (exceptions are TIFF and ICO formats). */ int GetImageCount(wxInputStream& stream); @@ -81,36 +81,33 @@ public: indicates which image to read from the stream. @param image - The image object which is to be affected by this operation. - + The image object which is to be affected by this operation. @param stream - Opened input stream for reading image data. - + Opened input stream for reading image data. @param verbose - If set to @true, errors reported by the image handler will produce wxLogMessages. - + If set to @true, errors reported by the image handler will produce + wxLogMessages. @param index - The index of the image in the file (starting from zero). + The index of the image in the file (starting from zero). @returns @true if the operation succeeded, @false otherwise. - @sa wxImage::LoadFile, wxImage::SaveFile, SaveFile() + @see wxImage::LoadFile, wxImage::SaveFile, SaveFile() */ bool LoadFile(wxImage* image, wxInputStream& stream, - bool verbose=@true, int index=0); + bool verbose = true, int index = 0); /** Saves a image in the output stream. @param image - The image object which is to be affected by this operation. - + The image object which is to be affected by this operation. @param stream - Opened output stream for writing the data. + Opened output stream for writing the data. @returns @true if the operation succeeded, @false otherwise. - @sa wxImage::LoadFile, wxImage::SaveFile, LoadFile() + @see wxImage::LoadFile, wxImage::SaveFile, LoadFile() */ bool SaveFile(wxImage* image, wxOutputStream& stream); @@ -118,7 +115,7 @@ public: Sets the handler extension. @param extension - Handler extension. + Handler extension. */ void SetExtension(const wxString& extension); @@ -126,7 +123,7 @@ public: Sets the handler MIME type. @param mimename - Handler MIME type. + Handler MIME type. */ void SetMimeType(const wxString& mimetype); @@ -134,7 +131,7 @@ public: Sets the handler name. @param name - Handler name. + Handler name. */ void SetName(const wxString& name); }; @@ -175,111 +172,185 @@ public: Creates an image from XPM data. @param width - Specifies the width of the image. - + Specifies the width of the image. @param height - Specifies the height of the image. - + Specifies the height of the image. @param name - Name of the file from which to load the image. - + Name of the file from which to load the image. @param stream - Opened input stream from which to load the image. Currently, the stream must - support seeking. - + Opened input stream from which to load the image. Currently, the stream + must support seeking. @param type - May be one of the following: + May be one of the following: - wxBITMAP_TYPE_BMP - Load a Windows bitmap file. - wxBITMAP_TYPE_GIF - Load a GIF bitmap file. + wxBITMAP_TYPE_BMP - wxBITMAP_TYPE_JPEG - Load a JPEG bitmap file. - wxBITMAP_TYPE_PNG + Load a Windows bitmap file. - Load a PNG bitmap file. - wxBITMAP_TYPE_PCX - Load a PCX bitmap file. + wxBITMAP_TYPE_GIF - wxBITMAP_TYPE_PNM - Load a PNM bitmap file. - wxBITMAP_TYPE_TIF + Load a GIF bitmap file. - Load a TIFF bitmap file. - wxBITMAP_TYPE_TGA - Load a TGA bitmap file. + wxBITMAP_TYPE_JPEG - wxBITMAP_TYPE_XPM - Load a XPM bitmap file. - wxBITMAP_TYPE_ICO + Load a JPEG bitmap file. - Load a Windows icon file (ICO). - wxBITMAP_TYPE_CUR - Load a Windows cursor file (CUR). + wxBITMAP_TYPE_PNG - wxBITMAP_TYPE_ANI - Load a Windows animated cursor file (ANI). - wxBITMAP_TYPE_ANY + Load a PNG bitmap file. - Will try to autodetect the format. - @param mimetype - MIME type string (for example 'image/jpeg') - @param index - Index of the image to load in the case that the image file contains multiple - images. - This is only used by GIF, ICO and TIFF handlers. The default value (-1) means - "choose the default image" and is interpreted as the first image (index=0) by - the GIF and TIFF handler and as the largest and most colourful one by the ICO - handler. + wxBITMAP_TYPE_PCX + + + + + Load a PCX bitmap file. + + + + + + wxBITMAP_TYPE_PNM + + + + + Load a PNM bitmap file. + + + + + + wxBITMAP_TYPE_TIF + + + + + Load a TIFF bitmap file. + + + + + + wxBITMAP_TYPE_TGA + + + + + Load a TGA bitmap file. + + + + + + wxBITMAP_TYPE_XPM + + + + + Load a XPM bitmap file. + + + + + + wxBITMAP_TYPE_ICO + + + + + Load a Windows icon file (ICO). + + + + + + wxBITMAP_TYPE_CUR + + + + + Load a Windows cursor file (CUR). + + + + + + wxBITMAP_TYPE_ANI + + + + + Load a Windows animated cursor file (ANI). + + + + + + wxBITMAP_TYPE_ANY + + + + + Will try to autodetect the format. + @param mimetype + MIME type string (for example 'image/jpeg') + @param index + Index of the image to load in the case that the image file contains + multiple images. + This is only used by GIF, ICO and TIFF handlers. The default value (-1) + means + "choose the default image" and is interpreted as the first image (index=0) + by + the GIF and TIFF handler and as the largest and most colourful one by the + ICO handler. @param xpmData - A pointer to XPM image data. + A pointer to XPM image data. @remarks Depending on how wxWidgets has been configured, not all formats - may be available. + may be available. - @sa LoadFile() + @see LoadFile() */ wxImage(); wxImage(const wxImage& image); wxImage(const wxBitmap& bitmap); - wxImage(int width, int height, bool clear=@true); + wxImage(int width, int height, bool clear = true); wxImage(int width, int height, unsigned char* data, - bool static_data = @false); + bool static_data = false); wxImage(const wxString& name, long type = wxBITMAP_TYPE_ANY, int index = -1); wxImage(const wxString& name, const wxString& mimetype, @@ -312,7 +383,7 @@ public: @e blurRadius. This should not be used when using a single mask colour for transparency. - @sa @ref horzblur() BlurHorizontal, @ref vertblur() BlurVertical + @see @ref horzblur() BlurHorizontal, @ref vertblur() BlurVertical */ wxImage Blur(int blurRadius); @@ -320,7 +391,7 @@ public: Blurs the image in the horizontal direction only. This should not be used when using a single mask colour for transparency. - @sa Blur(), @ref vertblur() BlurVertical + @see Blur(), @ref vertblur() BlurVertical */ wxImage BlurHorizontal(int blurRadius); @@ -328,19 +399,18 @@ public: Blurs the image in the vertical direction only. This should not be used when using a single mask colour for transparency. - @sa Blur(), @ref horzblur() BlurHorizontal + @see Blur(), @ref horzblur() BlurHorizontal */ wxImage BlurVertical(int blurRadius); /** Deletes all image handlers. - This function is called by wxWidgets on exit. */ static void CleanUpHandlers(); /** - Computes the histogram of the image. @e histogram is a reference to + Computes the histogram of the image. @a histogram is a reference to wxImageHistogram object. wxImageHistogram is a specialization of wxHashMap "template" and is defined as follows: @@ -350,10 +420,9 @@ public: /** If the image has alpha channel, this method converts it to mask. All pixels - with alpha value less than @e threshold are replaced with mask colour + with alpha value less than @a threshold are replaced with mask colour and the alpha channel is removed. Mask colour is chosen automatically using FindFirstUnusedColour(). - If the image image doesn't have alpha channel, ConvertAlphaToMask does nothing. @@ -390,19 +459,18 @@ public: wxImage Copy(); /** - Creates a fresh image. If @e clear is @true, the new image will be initialized + Creates a fresh image. If @a clear is @true, the new image will be initialized to black. Otherwise, the image data will be uninitialized. @param width - The width of the image in pixels. - + The width of the image in pixels. @param height - The height of the image in pixels. + The height of the image in pixels. @returns @true if the call succeeded, @false otherwise. */ - bool Create(int width, int height, bool clear=@true); + bool Create(int width, int height, bool clear = true); /** Destroys the image data. @@ -411,16 +479,15 @@ public: /** @param r,g,b - Pointers to variables to save the colour. - + Pointers to variables to save the colour. @param startR,startG,startB - Initial values of the colour. Returned colour - will have RGB values equal to or greater than these. + Initial values of the colour. Returned colour + will have RGB values equal to or greater than these. @returns Returns @false if there is no unused colour left, @true on success. */ - bool FindFirstUnusedColour(unsigned char * r, unsigned char * g, - unsigned char * b, + bool FindFirstUnusedColour(unsigned char* r, unsigned char* g, + unsigned char* b, unsigned char startR = 1, unsigned char startG = 0, unsigned char startB = 0); @@ -430,20 +497,17 @@ public: Finds the handler associated with the given MIME type. @param name - The handler name. - + The handler name. @param extension - The file extension, such as "bmp". - + The file extension, such as "bmp". @param imageType - The image type, such as wxBITMAP_TYPE_BMP. - + The image type, such as wxBITMAP_TYPE_BMP. @param mimetype - MIME type. + MIME type. @returns A pointer to the handler if found, @NULL otherwise. - @sa wxImageHandler + @see wxImageHandler */ static wxImageHandler* FindHandler(const wxString& name); static wxImageHandler* FindHandler(const wxString& extension, @@ -460,7 +524,7 @@ public: which are stored as the @ref getdata() RGB ones. */ unsigned char GetAlpha(int x, int y); - unsigned char * GetAlpha(); + unsigned char* GetAlpha(); //@} /** @@ -476,7 +540,6 @@ public: the first row, the second one --- to the second pixel of the first row and so on until the end of the first row, with second row following after it and so on. - You should not delete the returned pointer nor pass it to SetData(). */ @@ -490,7 +553,7 @@ public: /** Returns the static list of image format handlers. - @sa wxImageHandler + @see wxImageHandler */ static wxList GetHandlers(); @@ -506,76 +569,148 @@ public: available images. @param name - Name of the file to query. - + Name of the file to query. @param stream - Opened input stream with image data. Currently, the stream must support seeking. - + Opened input stream with image data. Currently, the stream must support + seeking. @param type - May be one of the following: + May be one of the following: + + + + + + + wxBITMAP_TYPE_BMP + + + + + Load a Windows bitmap file. + + + + + + wxBITMAP_TYPE_GIF + + + + + Load a GIF bitmap file. + + + + + + wxBITMAP_TYPE_JPEG + + + + + Load a JPEG bitmap file. + + + + + + wxBITMAP_TYPE_PNG + + + + + Load a PNG bitmap file. + + + + + + wxBITMAP_TYPE_PCX + + + + + Load a PCX bitmap file. + + + + + + wxBITMAP_TYPE_PNM + + + + + Load a PNM bitmap file. + + + + + + wxBITMAP_TYPE_TIF + + + + + Load a TIFF bitmap file. + + + + + + wxBITMAP_TYPE_XPM + - wxBITMAP_TYPE_BMP - Load a Windows bitmap file. + Load a XPM bitmap file. - wxBITMAP_TYPE_GIF - Load a GIF bitmap file. - wxBITMAP_TYPE_JPEG + wxBITMAP_TYPE_ICO - Load a JPEG bitmap file. - wxBITMAP_TYPE_PNG - Load a PNG bitmap file. + Load a Windows icon file (ICO). - wxBITMAP_TYPE_PCX - Load a PCX bitmap file. - wxBITMAP_TYPE_PNM + wxBITMAP_TYPE_CUR - Load a PNM bitmap file. - wxBITMAP_TYPE_TIF - Load a TIFF bitmap file. + Load a Windows cursor file (CUR). - wxBITMAP_TYPE_XPM - Load a XPM bitmap file. - wxBITMAP_TYPE_ICO + wxBITMAP_TYPE_ANI - Load a Windows icon file (ICO). - wxBITMAP_TYPE_CUR - Load a Windows cursor file (CUR). + Load a Windows animated cursor file (ANI). - wxBITMAP_TYPE_ANI - Load a Windows animated cursor file (ANI). - wxBITMAP_TYPE_ANY + wxBITMAP_TYPE_ANY - Will try to autodetect the format. + + + + Will try to autodetect the format. @returns Number of available images. For most image handlers, this is 1 - (exceptions are TIFF and ICO formats). + (exceptions are TIFF and ICO formats). */ static int GetImageCount(const wxString& filename, long type = wxBITMAP_TYPE_ANY); @@ -589,9 +724,9 @@ public: suitable for passing to file open/save dialog boxes. @returns The format of the returned string is - "(*.ext1;*.ext2)|*.ext1;*.ext2". + "(*.ext1;*.ext2)|*.ext1;*.ext2". - @sa wxImageHandler + @see wxImageHandler */ static wxString GetImageExtWildcard(); @@ -612,55 +747,44 @@ public: /** Gets a user-defined option. The function is case-insensitive to @e name. - For example, when saving as a JPEG file, the option @b quality is used, which is a number between 0 and 100 (0 is terrible, 100 is very good). - @sa SetOption(), GetOptionInt(), HasOption() + @see SetOption(), GetOptionInt(), HasOption() */ wxString GetOption(const wxString& name); /** Gets a user-defined option as an integer. The function is case-insensitive to @e name. - If the given option is not present, the function returns 0. Use HasOption() is 0 is a possibly valid value for the option. - Options for wxPNGHandler - wxIMAGE_OPTION_PNG_FORMAT - Format for saving a PNG file. wxIMAGE_OPTION_PNG_BITDEPTH - Bit depth for every channel (R/G/B/A). Supported values for wxIMAGE_OPTION_PNG_FORMAT: - wxPNG_TYPE_COLOUR - Stores RGB image. wxPNG_TYPE_GREY - Stores grey image, converts from RGB. wxPNG_TYPE_GREY_RED - Stores grey image, uses red value as grey. - - @sa SetOption(), GetOption() + @see SetOption(), GetOption() */ int GetOptionInt(const wxString& name); @@ -693,7 +817,7 @@ public: /** Gets the width of the image in pixels. - @sa GetHeight() + @see GetHeight() */ int GetWidth(); @@ -709,12 +833,12 @@ public: /** Converts a color in HSV color space to RGB color space. */ -#define wxImage::RGBValue HSVtoRGB(const HSVValue & hsv) /* implementation is private */ +#define wxImage::RGBValue HSVtoRGB(const HSVValue& hsv) /* implementation is private */ /** Returns @true if this image has alpha channel, @false otherwise. - @sa GetAlpha(), SetAlpha() + @see GetAlpha(), SetAlpha() */ bool HasAlpha(); @@ -727,7 +851,7 @@ public: Returns @true if the given option is present. The function is case-insensitive to @e name. - @sa SetOption(), GetOption(), GetOptionInt() + @see SetOption(), GetOption(), GetOptionInt() */ bool HasOption(const wxString& name); @@ -742,11 +866,10 @@ public: /** Internal use only. Adds standard image format handlers. It only install BMP for the time being, which is used by wxBitmap. - This function is called by wxWidgets on startup, and shouldn't be called by the user. - @sa wxImageHandler, wxInitAllImageHandlers, wxQuantize + @see wxImageHandler, wxInitAllImageHandlers, wxQuantize */ static void InitStandardHandlers(); @@ -754,17 +877,17 @@ public: Adds a handler at the start of the static list of format handlers. @param handler - A new image format handler object. There is usually only one instance - of a given handler class in an application session. + A new image format handler object. There is usually only one instance + of a given handler class in an application session. - @sa wxImageHandler + @see wxImageHandler */ static void InsertHandler(wxImageHandler* handler); /** Returns @true if image data is present. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** Returns @true if the given pixel is transparent, i.e. either has the mask @@ -778,94 +901,165 @@ public: Loads an image from an input stream. @param name - Name of the file from which to load the image. - + Name of the file from which to load the image. @param stream - Opened input stream from which to load the image. Currently, the stream must - support seeking. - + Opened input stream from which to load the image. Currently, the stream + must support seeking. @param type - One of the following values: + One of the following values: - wxBITMAP_TYPE_BMP - Load a Windows image file. - wxBITMAP_TYPE_GIF - Load a GIF image file. + wxBITMAP_TYPE_BMP - wxBITMAP_TYPE_JPEG - Load a JPEG image file. - wxBITMAP_TYPE_PCX + Load a Windows image file. - Load a PCX image file. - wxBITMAP_TYPE_PNG - Load a PNG image file. + wxBITMAP_TYPE_GIF - wxBITMAP_TYPE_PNM - Load a PNM image file. - wxBITMAP_TYPE_TIF + Load a GIF image file. - Load a TIFF image file. - wxBITMAP_TYPE_XPM - Load a XPM image file. + wxBITMAP_TYPE_JPEG - wxBITMAP_TYPE_ICO - Load a Windows icon file (ICO). - wxBITMAP_TYPE_CUR + Load a JPEG image file. - Load a Windows cursor file (CUR). - wxBITMAP_TYPE_ANI - Load a Windows animated cursor file (ANI). + wxBITMAP_TYPE_PCX + + + + + Load a PCX image file. + + + + + + wxBITMAP_TYPE_PNG + + + + + Load a PNG image file. + + + + + + wxBITMAP_TYPE_PNM + + + + + Load a PNM image file. + + + + + + wxBITMAP_TYPE_TIF + + + + + Load a TIFF image file. + + + + + + wxBITMAP_TYPE_XPM + + + + + Load a XPM image file. + + + + + + wxBITMAP_TYPE_ICO + + + + + Load a Windows icon file (ICO). + + + + + + wxBITMAP_TYPE_CUR + + + + + Load a Windows cursor file (CUR). + + + + + + wxBITMAP_TYPE_ANI + + + + + Load a Windows animated cursor file (ANI). - wxBITMAP_TYPE_ANY - Will try to autodetect the format. - @param mimetype - MIME type string (for example 'image/jpeg') + wxBITMAP_TYPE_ANY + + + + + Will try to autodetect the format. + @param mimetype + MIME type string (for example 'image/jpeg') @param index - Index of the image to load in the case that the image file contains multiple - images. - This is only used by GIF, ICO and TIFF handlers. The default value (-1) means - "choose the default image" and is interpreted as the first image (index=0) by - the GIF and TIFF handler and as the largest and most colourful one by the ICO - handler. + Index of the image to load in the case that the image file contains + multiple images. + This is only used by GIF, ICO and TIFF handlers. The default value (-1) + means + "choose the default image" and is interpreted as the first image (index=0) + by + the GIF and TIFF handler and as the largest and most colourful one by the + ICO handler. @returns @true if the operation succeeded, @false otherwise. If the - optional index parameter is out of range, @false is - returned and a call to wxLogError() takes place. + optional index parameter is out of range, @false is + returned and a call to wxLogError() takes place. @remarks Depending on how wxWidgets has been configured, not all formats - may be available. + may be available. - @sa SaveFile() + @see SaveFile() */ bool LoadFile(const wxString& name, long type = wxBITMAP_TYPE_ANY, @@ -883,10 +1077,10 @@ public: Returns a mirrored copy of the image. The parameter @e horizontally indicates the orientation. */ - wxImage Mirror(bool horizontally = @true); + wxImage Mirror(bool horizontally = true); /** - Copy the data of the given @e image to the specified position in this image. + Copy the data of the given @a image to the specified position in this image. */ void Paste(const wxImage& image, int x, int y); @@ -910,11 +1104,11 @@ public: is not deleted. @param name - The handler name. + The handler name. @returns @true if the handler was found and removed, @false otherwise. - @sa wxImageHandler + @see wxImageHandler */ static bool RemoveHandler(const wxString& name); @@ -929,12 +1123,10 @@ public: Changes the size of the image in-place by scaling it: after a call to this function, the image will have the given width and height. - - For a description of the @e quality parameter, see the Scale() function. - + For a description of the @a quality parameter, see the Scale() function. Returns the (modified) image itself. - @sa Scale() + @see Scale() */ wxImage Rescale(int width, int height, int quality = wxIMAGE_QUALITY_NORMAL); @@ -943,36 +1135,34 @@ public: Changes the size of the image in-place without scaling it by adding either a border with the given colour or cropping as necessary. The image is pasted into a new - image with the given @e size and background colour at the position @e pos - relative to the upper left of the new image. If @e red = green = blue = -1 + image with the given @a size and background colour at the position @e pos + relative to the upper left of the new image. If @a red = green = blue = -1 then use either the current mask colour if set or find, use, and set a suitable mask colour for any newly exposed areas. - Returns the (modified) image itself. - @sa Size() + @see Size() */ wxImage Resize(const wxSize& size, const wxPoint pos, int red = -1, int green = -1, int blue = -1); /** - Rotates the image about the given point, by @e angle radians. Passing @true - to @e interpolating results in better image quality, but is slower. If the + Rotates the image about the given point, by @a angle radians. Passing @true + to @a interpolating results in better image quality, but is slower. If the image has a mask, then the mask colour is used for the uncovered pixels in the rotated image background. Else, black (rgb 0, 0, 0) will be used. - Returns the rotated image, leaving this image intact. */ wxImage Rotate(double angle, const wxPoint& rotationCentre, - bool interpolating = @true, - wxPoint* offsetAfterRotation = @NULL); + bool interpolating = true, + wxPoint* offsetAfterRotation = NULL); /** Returns a copy of the image rotated 90 degrees in the direction indicated by @e clockwise. */ - wxImage Rotate90(bool clockwise = @true); + wxImage Rotate90(bool clockwise = true); /** Rotates the hue of each pixel in the image by @e angle, which is a double in @@ -987,70 +1177,122 @@ public: Saves an image in the given stream. @param name - Name of the file to save the image to. - + Name of the file to save the image to. @param stream - Opened output stream to save the image to. - + Opened output stream to save the image to. @param type - Currently these types can be used: + Currently these types can be used: + + + + + + + wxBITMAP_TYPE_BMP + + + + + Save a BMP image file. + + + + + + wxBITMAP_TYPE_JPEG + + + + + Save a JPEG image file. + + + + + + wxBITMAP_TYPE_PNG + + + + + Save a PNG image file. + + + + - wxBITMAP_TYPE_BMP + wxBITMAP_TYPE_PCX - Save a BMP image file. - wxBITMAP_TYPE_JPEG + Save a PCX image file (tries to save as 8-bit if possible, falls back to + 24-bit otherwise). - Save a JPEG image file. - wxBITMAP_TYPE_PNG - Save a PNG image file. - wxBITMAP_TYPE_PCX + wxBITMAP_TYPE_PNM - Save a PCX image file (tries to save as 8-bit if possible, falls back to 24-bit - otherwise). - wxBITMAP_TYPE_PNM + Save a PNM image file (as raw RGB always). - Save a PNM image file (as raw RGB always). - wxBITMAP_TYPE_TIFF - Save a TIFF image file. - wxBITMAP_TYPE_XPM + wxBITMAP_TYPE_TIFF - Save a XPM image file. - wxBITMAP_TYPE_ICO + Save a TIFF image file. - Save a Windows icon file (ICO) (the size may be up to 255 wide by 127 high. A - single image is saved in 8 colors at the size supplied). - wxBITMAP_TYPE_CUR - Save a Windows cursor file (CUR). + wxBITMAP_TYPE_XPM + + + + + Save a XPM image file. + + + + + + wxBITMAP_TYPE_ICO + + + + + Save a Windows icon file (ICO) (the size may be up to 255 wide by 127 high. + A single image is saved in 8 colors at the size supplied). + + + + + + wxBITMAP_TYPE_CUR + + + + + Save a Windows cursor file (CUR). @param mimetype - MIME type. + MIME type. @returns @true if the operation succeeded, @false otherwise. @remarks Depending on how wxWidgets has been configured, not all formats - may be available. + may be available. - @sa LoadFile() + @see LoadFile() */ bool SaveFile(const wxString& name, int type); bool SaveFile(const wxString& name, const wxString& mimetype); @@ -1064,7 +1306,6 @@ public: Returns a scaled version of the image. This is also useful for scaling bitmaps in general as the only other way to scale bitmaps is to blit a wxMemoryDC into another wxMemoryDC. - It should be noted that although using wxIMAGE_QUALITY_HIGH produces much nicer looking results it is a slower method. Downsampling will use the box averaging method @@ -1074,30 +1315,41 @@ public: it will be quite substantially slower as the bicubic algorithm has to process a lot of data. - It should also be noted that the high quality scaling may not work as expected when using a single mask colour for transparency, as the scaling will blur the image and will therefore remove the mask partially. Using the alpha channel will work. - Example: @param quality - Determines what method to use for resampling the image. Can be one of the + Determines what method to use for resampling the image. Can be one of the following: - wxIMAGE_QUALITY_NORMAL - Uses the normal default scaling method of pixel replication - wxIMAGE_QUALITY_HIGH - Uses bicubic and box averaging resampling methods for upsampling and + wxIMAGE_QUALITY_NORMAL + + + + + Uses the normal default scaling method of pixel replication + + + + + + wxIMAGE_QUALITY_HIGH + + + + + Uses bicubic and box averaging resampling methods for upsampling and downsampling respectively - @sa Rescale() + @see Rescale() */ wxImage Scale(int width, int height, int quality = wxIMAGE_QUALITY_NORMAL); @@ -1108,8 +1360,8 @@ public: if the image has alpha channel data, use HasAlpha() to check for this. */ - void SetAlpha(unsigned char * alpha = @NULL, - bool static_data = @false); + void SetAlpha(unsigned char* alpha = NULL, + bool static_data = false); void SetAlpha(int x, int y, unsigned char alpha); //@} @@ -1117,10 +1369,8 @@ public: Sets the image data without performing checks. The data given must have the size (width*height*3) or results will be unexpected. Don't use this method if you aren't sure you know what you are doing. - The data must have been allocated with @c malloc(), @b NOT with @c operator new. - After this call the pointer to the data is owned by the wxImage object, that will be responsible for deleting it. Do not pass to this function a pointer obtained through @@ -1132,7 +1382,7 @@ public: Specifies whether there is a mask or not. The area of the mask is determined by the current mask colour. */ - void SetMask(bool hasMask = @true); + void SetMask(bool hasMask = true); /** Sets the mask colour for this image (and tells the image to use the mask). @@ -1142,15 +1392,14 @@ public: /** @param mask - The mask image to extract mask shape from. Must have same dimensions as the + The mask image to extract mask shape from. Must have same dimensions as the image. - @param mr,mg,mb - RGB value of pixels in mask that will be used to create the mask. + RGB value of pixels in mask that will be used to create the mask. @returns Returns @false if mask does not have same dimensions as the image - or if there is no unused colour left. Returns @true if - the mask was successfully applied. + or if there is no unused colour left. Returns @true if + the mask was successfully applied. */ bool SetMaskFromImage(const wxImage& mask, unsigned char mr, unsigned char mg, @@ -1159,11 +1408,10 @@ public: //@{ /** Sets a user-defined option. The function is case-insensitive to @e name. - For example, when saving as a JPEG file, the option @b quality is used, which is a number between 0 and 100 (0 is terrible, 100 is very good). - @sa GetOption(), GetOptionInt(), HasOption() + @see GetOption(), GetOptionInt(), HasOption() */ void SetOption(const wxString& name, const wxString& value); void SetOption(const wxString& name, int value); @@ -1182,22 +1430,22 @@ public: manipulate the data. */ -#define void SetRGB(wxRect & rect, unsigned char red, - unsigned char green, - unsigned char blue) /* implementation is private */ + void SetRGB(wxRect& rect, unsigned char red, + unsigned char green, + unsigned char blue); /** Returns a resized version of this image without scaling it by adding either a border with the given colour or cropping as necessary. The image is pasted into a new - image with the given @e size and background colour at the position @e pos - relative to the upper left of the new image. If @e red = green = blue = -1 + image with the given @a size and background colour at the position @e pos + relative to the upper left of the new image. If @a red = green = blue = -1 then the areas of the larger image not covered by this image are made transparent by filling them with the image mask colour (which will be allocated automatically if it isn't currently set). Otherwise, the areas will be filled with the colour with the specified RGB components. - @sa Resize() + @see Resize() */ wxImage Size(const wxSize& size, const wxPoint pos, int red = -1, int green = -1, int blue = -1); @@ -1206,7 +1454,7 @@ public: Assignment operator, using @ref overview_trefcount "reference counting". @param image - Image to assign. + Image to assign. @returns Returns 'this' object. */ @@ -1222,7 +1470,7 @@ public: Initializes all available image handlers. For a list of available handlers, see wxImage. - @sa wxImage, wxImageHandler + @see wxImage, wxImageHandler */ void wxInitAllImageHandlers(); diff --git a/interface/imaglist.h b/interface/imaglist.h index b360a9c751..6fab7a10c5 100644 --- a/interface/imaglist.h +++ b/interface/imaglist.h @@ -33,21 +33,18 @@ public: and the initial size of the list. @param width - Width of the images in the list. - + Width of the images in the list. @param height - Height of the images in the list. - + Height of the images in the list. @param mask - @true if masks should be created for all images. - + @true if masks should be created for all images. @param initialCount - The initial size of the list. + The initial size of the list. - @sa Create() + @see Create() */ wxImageList(); - wxImageList(int width, int height, bool mask = @true, + wxImageList(int width, int height, bool mask = true, int initialCount = 1); //@} @@ -56,21 +53,18 @@ public: Adds a new image using an icon. @param bitmap - Bitmap representing the opaque areas of the image. - + Bitmap representing the opaque areas of the image. @param mask - Monochrome mask bitmap, representing the transparent areas of the image. - + Monochrome mask bitmap, representing the transparent areas of the image. @param maskColour - Colour indicating which parts of the image are transparent. - + Colour indicating which parts of the image are transparent. @param icon - Icon to use as the image. + Icon to use as the image. @returns The new zero-based image index. @remarks The original bitmap or icon is not affected by the Add - operation, and can be deleted afterwards. + operation, and can be deleted afterwards. */ int Add(const wxBitmap& bitmap, const wxBitmap& mask = wxNullBitmap); @@ -81,54 +75,74 @@ public: /** Initializes the list. See wxImageList() for details. */ - bool Create(int width, int height, bool mask = @true, + bool Create(int width, int height, bool mask = true, int initialCount = 1); /** Draws a specified image onto a device context. @param index - Image index, starting from zero. - + Image index, starting from zero. @param dc - Device context to draw on. - + Device context to draw on. @param x - X position on the device context. - + X position on the device context. @param y - Y position on the device context. - + Y position on the device context. @param flags - How to draw the image. A bitlist of a selection of the following: + How to draw the image. A bitlist of a selection of the following: + + + + + + + wxIMAGELIST_DRAW_NORMAL + + + - wxIMAGELIST_DRAW_NORMAL + Draw the image normally. - Draw the image normally. - wxIMAGELIST_DRAW_TRANSPARENT - Draw the image with transparency. + wxIMAGELIST_DRAW_TRANSPARENT - wxIMAGELIST_DRAW_SELECTED - Draw the image in selected state. - wxIMAGELIST_DRAW_FOCUSED + Draw the image with transparency. - Draw the image in a focused state. + + + wxIMAGELIST_DRAW_SELECTED + + + + + Draw the image in selected state. + + + + + + wxIMAGELIST_DRAW_FOCUSED + + + + + Draw the image in a focused state. @param solidBackground - For optimisation - drawing can be faster if the function is told - that the background is solid. + For optimisation - drawing can be faster if the function is told + that the background is solid. */ bool Draw(int index, wxDC& dc, int x, int y, int flags = wxIMAGELIST_DRAW_NORMAL, - bool solidBackground = @false); + bool solidBackground = false); /** Returns the bitmap corresponding to the given index. @@ -146,22 +160,20 @@ public: int GetImageCount(); /** - Retrieves the size of the images in the list. Currently, the @e index + Retrieves the size of the images in the list. Currently, the @a index parameter is ignored as all images in the list have the same size. @param index - currently unused, should be 0 - + currently unused, should be 0 @param width - receives the width of the images in the list - + receives the width of the images in the list @param height - receives the height of the images in the list + receives the height of the images in the list @returns @true if the function succeeded, @false if it failed (for example, - if the image list was not yet initialized). + if the image list was not yet initialized). */ - bool GetSize(int index, int& width, int & height); + bool GetSize(int index, int& width, int& height); /** Removes the image at the given position. @@ -178,18 +190,16 @@ public: Replaces the existing image with the new image. @param bitmap - Bitmap representing the opaque areas of the image. - + Bitmap representing the opaque areas of the image. @param mask - Monochrome mask bitmap, representing the transparent areas of the image. - + Monochrome mask bitmap, representing the transparent areas of the image. @param icon - Icon to use as the image. + Icon to use as the image. @returns @true if the replacement was successful, @false otherwise. @remarks The original bitmap or icon is not affected by the Replace - operation, and can be deleted afterwards. + operation, and can be deleted afterwards. */ bool Replace(int index, const wxBitmap& bitmap, const wxBitmap& mask = wxNullBitmap); diff --git a/interface/init.h b/interface/init.h index d0c0749942..ba0ac3249b 100644 --- a/interface/init.h +++ b/interface/init.h @@ -15,13 +15,13 @@ void wxEntryCleanup(); //@{ /** (notice that under Windows CE platform, and only there, the type of - @e pCmdLine is @c wchar_t *, otherwise it is @c char *, even in + @a pCmdLine is @c wchar_t *, otherwise it is @c char *, even in Unicode build). */ -bool wxEntryStart(int& argc, wxChar ** argv); +bool wxEntryStart(int& argc, wxChar** argv); bool wxEntryStart(HINSTANCE hInstance, - HINSTANCE hPrevInstance = @NULL, - char * pCmdLine = @NULL, + HINSTANCE hPrevInstance = NULL, + char* pCmdLine = NULL, int nCmdShow = SW_SHOWNORMAL); //@} diff --git a/interface/intl.h b/interface/intl.h index dc3af3d166..854d3c352e 100644 --- a/interface/intl.h +++ b/interface/intl.h @@ -55,8 +55,8 @@ @category{FIXME} @seealso - @ref overview_internationalization "Internationalization overview", @ref - overview_sampleinternat "Internat sample", wxXLocale + @ref overview_internationalization, @ref overview_sampleinternat "Internat + sample", wxXLocale */ class wxLocale { @@ -64,7 +64,6 @@ public: //@{ /** See Init() for parameters description. - The call of this function has several global side effects which you should understand: first of all, the application locale is changed - note that this will affect many of standard C library functions such as printf() or strftime(). @@ -79,8 +78,8 @@ public: wxLocale(const wxString& name, const wxString& short = wxEmptyString, const wxString& locale = wxEmptyString, - bool bLoadDefault = @true, - bool bConvertEncoding = @false); + bool bLoadDefault = true, + bool bConvertEncoding = false); //@} /** @@ -97,32 +96,25 @@ public: places (current directory first, then the system one), but you may also prepend additional directories to the search path with AddCatalogLookupPathPrefix(). - All loaded catalogs will be used for message lookup by GetString() for the current locale. - Returns @true if catalog was successfully loaded, @false otherwise (which might mean that the catalog is not found or that it isn't in the correct format). - The second form of this method takes two additional arguments, - @e msgIdLanguage and @e msgIdCharset. - - @e msgIdLanguage specifies the language of "msgid" strings in source code + @a msgIdLanguage and @e msgIdCharset. + @a msgIdLanguage specifies the language of "msgid" strings in source code (i.e. arguments to GetString(), wxGetTranslation and the _ macro). It is used if AddCatalog cannot find any catalog for current language: if the language is same as source code language, then strings from source code are used instead. - - @e msgIdCharset lets you specify the charset used for msgids in sources + @a msgIdCharset lets you specify the charset used for msgids in sources in case they use 8-bit characters (e.g. German or French strings). This argument has no effect in Unicode build, because literals in sources are Unicode strings; you have to use compiler-specific method of setting the right charset when compiling with Unicode. - By default (i.e. when you use the first form), msgid strings are assumed to be in English and written only using 7-bit ASCII characters. - If you have to deal with non-English strings or 8-bit characters in the source code, see the instructions in @ref overview_nonenglishoverview "Writing non-English applications". @@ -137,7 +129,6 @@ public: Add a prefix to the catalog lookup path: the message catalog files will be looked up under prefix/lang/LC_MESSAGES, prefix/lang and prefix (in this order). - This only applies to subsequent invocations of AddCatalog(). */ void AddCatalogLookupPathPrefix(const wxString& prefix); @@ -146,11 +137,8 @@ public: Adds custom, user-defined language to the database of known languages. This database is used in conjunction with the first form of Init(). - wxLanguageInfo is defined as follows: - @e Language should be greater than wxLANGUAGE_USER_DEFINED. - Wx::LanguageInfo-new( language, canonicalName, WinLang, WinSubLang, Description ) */ @@ -161,29 +149,26 @@ public: given locale, specified either as a two letter ISO language code (for example, "pt"), a language code followed by the country code ("pt_BR") or a full, human readable, language description ("Portuguese-Brazil"). - Returns the information for the given language or @NULL if this language is unknown. Note that even if the returned pointer is valid, the caller should @e not delete it. - @sa GetLanguageInfo() + @see GetLanguageInfo() */ - static wxLanguageInfo * FindLanguageInfo(const wxString& locale); + static wxLanguageInfo* FindLanguageInfo(const wxString& locale); /** Returns the canonical form of current locale name. Canonical form is the one that is used on UNIX systems: it is a two- or five-letter string in xx or xx_YY format, where xx is ISO 639 code of language and YY is ISO 3166 code of the country. Examples are "en", "en_GB", "en_US" or "fr_FR". - This form is internally used when looking up message catalogs. - Compare GetSysName(). */ wxString GetCanonicalName(); /** - Returns the header value for header @e header. The search for @e header is case + Returns the header value for header @e header. The search for @a header is case sensitive. If an @e domain is passed, this domain is searched. Else all domains will be searched until a header has been found. @@ -203,20 +188,17 @@ public: Returns a pointer to wxLanguageInfo structure containing information about the given language or @NULL if this language is unknown. Note that even if the returned pointer is valid, the caller should @e not delete it. - See AddLanguage() for the wxLanguageInfo description. - As with Init(), @c wxLANGUAGE_DEFAULT has the special meaning if passed as an argument to this function and in this case the result of GetSystemLanguage() is used. */ - static wxLanguageInfo * GetLanguageInfo(int lang); + static wxLanguageInfo* GetLanguageInfo(int lang); /** Returns English name of the given language or empty string if this language is unknown. - See GetLanguageInfo() for a remark about special meaning of @c wxLANGUAGE_DEFAULT. */ @@ -239,39 +221,35 @@ public: /** Retrieves the translation for a string in all loaded domains unless the szDomain parameter is specified (and then only this catalog/domain is searched). - Returns original string if translation is not available (in this case an error message is generated the first time a string is not found; use wxLogNull to suppress it). - The second form is used when retrieving translation of string that has different singular and plural form in English or different plural forms in some other language. It takes two extra arguments: @e origString parameter must contain the singular form of the string to be converted. It is also used as the key for the search in the catalog. - The @e origString2 parameter is the plural form (in English). - The parameter @e n is used to determine the plural form. If no - message catalog is found @e origString is returned if 'n == 1', + The @a origString2 parameter is the plural form (in English). + The parameter @a n is used to determine the plural form. If no + message catalog is found @a origString is returned if 'n == 1', otherwise @e origString2. See GNU gettext manual for additional information on plural forms handling. - This method is called by the wxGetTranslation function and _ macro. @remarks Domains are searched in the last to first order, i.e. catalogs - added later override those added before. + added later override those added before. */ const wxString GetString(const wxString& origString, const wxString& domain = wxEmptyString); const wxString GetString(const wxString& origString, const wxString& origString2, size_t n, - const wxString& domain = @NULL); + const wxString& domain = NULL); //@} /** Returns current platform-specific locale name as passed to setlocale(). - Compare GetCanonicalName(). */ wxString GetSysName(); @@ -288,7 +266,6 @@ public: particularly useful for the application as its form is platform-dependent and so you should probably use GetSystemEncoding() instead. - Returns a user-readable string value or an empty string if it couldn't be determined. */ @@ -307,54 +284,65 @@ public: doing. @param language - wxLanguage identifier of the locale. - wxLANGUAGE_DEFAULT has special meaning -- wxLocale will use system's default - language (see GetSystemLanguage). - + wxLanguage identifier of the locale. + wxLANGUAGE_DEFAULT has special meaning -- wxLocale will use system's + default + language (see GetSystemLanguage). @param flags - Combination of the following: + Combination of the following: - wxLOCALE_LOAD_DEFAULT - Load the message catalog - for the given locale containing the translations of standard wxWidgets messages - automatically. - wxLOCALE_CONV_ENCODING - Automatically convert message - catalogs to platform's default encoding. Note that it will do only basic - conversion between well-known pair like iso8859-1 and windows-1252 or - iso8859-2 and windows-1250. See Writing non-English applications for detailed - description of this behaviour. Note that this flag is meaningless in Unicode - build. + wxLOCALE_LOAD_DEFAULT - @param name - The name of the locale. Only used in diagnostic messages. - @param short - The standard 2 letter locale abbreviation; it is used as the - directory prefix when looking for the message catalog files. - @param locale - The parameter for the call to setlocale(). Note that it is - platform-specific. - @param bLoadDefault - May be set to @false to prevent loading of the message catalog - for the given locale containing the translations of standard wxWidgets messages. - This parameter would be rarely used in normal circumstances. + Load the message catalog + for the given locale containing the translations of standard wxWidgets + messages + automatically. + + + + + wxLOCALE_CONV_ENCODING + + + + + Automatically convert message + catalogs to platform's default encoding. Note that it will do only basic + conversion between well-known pair like iso8859-1 and windows-1252 or + iso8859-2 and windows-1250. See Writing non-English applications for + detailed + description of this behaviour. Note that this flag is meaningless in + Unicode build. + @param name + The name of the locale. Only used in diagnostic messages. + @param short + The standard 2 letter locale abbreviation; it is used as the + directory prefix when looking for the message catalog files. + @param locale + The parameter for the call to setlocale(). Note that it is + platform-specific. + @param bLoadDefault + May be set to @false to prevent loading of the message catalog + for the given locale containing the translations of standard wxWidgets + messages. + This parameter would be rarely used in normal circumstances. @param bConvertEncoding - May be set to @true to do automatic conversion of message - catalogs to platform's native encoding. Note that it will do only basic - conversion between well-known pair like iso8859-1 and windows-1252 or - iso8859-2 and windows-1250. - See Writing non-English applications for detailed - description of this behaviour. + May be set to @true to do automatic conversion of message + catalogs to platform's native encoding. Note that it will do only basic + conversion between well-known pair like iso8859-1 and windows-1252 or + iso8859-2 and windows-1250. + See Writing non-English applications for detailed + description of this behaviour. */ bool Init(int language = wxLANGUAGE_DEFAULT, int flags = @@ -362,8 +350,8 @@ public: bool Init(const wxString& name, const wxString& short = wxEmptyString, const wxString& locale = wxEmptyString, - bool bLoadDefault = @true, - bool bConvertEncoding = @false); + bool bLoadDefault = true, + bool bConvertEncoding = false); //@} /** @@ -371,23 +359,19 @@ public: this locale. For example in Windows 2000 and Windows XP, support for many locales is not installed by default. Returns @true if the locale is supported. - - The argument @e lang is the wxLanguage identifier. To obtain this for a + The argument @a lang is the wxLanguage identifier. To obtain this for a given a two letter ISO language code, use FindLanguageInfo() to obtain its wxLanguageInfo structure. See AddLanguage() for the wxLanguageInfo description. - This function is new since wxWidgets version 2.7.1. */ static bool IsAvailable(int lang); /** Check if the given catalog is loaded, and returns @true if it is. - According to GNU gettext tradition, each catalog normally corresponds to 'domain' which is more or less the application name. - See also: AddCatalog() */ bool IsLoaded(const char* domain); @@ -395,7 +379,7 @@ public: /** Returns @true if the locale could be set successfully. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** See @ref overview_languagecodes "list of recognized language constants". @@ -482,7 +466,7 @@ public: */ wxLocale(); wxLocale(wxLanguage lang); - wxLocale(const char * loc); + wxLocale(const char* loc); //@} /** @@ -491,14 +475,12 @@ public: most of the recent Unix systems (including Linux, various BSD and Mac OS X) and Microsoft Visual C++ standard library provides a similar API starting from version 8 (Visual Studio 2005). - If neither POSIX API nor Microsoft proprietary equivalent are available, this class is still available but works in degraded mode: the only supported locale is the C one and attempts to create wxXLocale object for any other locale will fail. You can use the preprocessor macro @c wxHAS_XLOCALE_SUPPORT to test if full xlocale API is available or only skeleton C locale support is present. - Notice that wxXLocale is new in wxWidgets 2.9.0 and is not compiled in if @c wxUSE_XLOCALE was set to 0 during the library compilation. */ @@ -534,20 +516,18 @@ public: or @false otherwise. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** Currently the following @c _l-functions are available: - Character classification functions: @c wxIsxxx_l(), e.g. @c wxIsalpha_l(), @c wxIslower_l() and all the others. Character transformation functions: @c wxTolower_l() and @c wxToupper_l() - We hope to provide many more functions (covering numbers, time and formatted IO) in the near future. - @sa wxLocale + @see wxLocale */ }; @@ -567,7 +547,6 @@ size_t n) /* implementation is private */ /** This macro doesn't do anything in the program code -- it simply expands to the value of its argument. - However it does have a purpose which is to mark the literal strings for the extraction into the message catalog created by @c xgettext program. Usually this is achieved using _ but that macro not only marks @@ -575,12 +554,12 @@ size_t n) /* implementation is private */ wxGetTranslation function call which means that it cannot be used in some situations, notably for static array initialization. - Here is an example which should make it more clear: suppose that you have a static array of strings containing the weekday names and which have to be translated (note that it is a bad example, really, as wxDateTime already can be used to get the localized week day names already). If you write + @code static const char * const weekdays[] = { _("Mon"), ..., _("Sun") }; ... @@ -589,6 +568,7 @@ size_t n) /* implementation is private */ the code wouldn't compile because the function calls are forbidden in the array initializer. So instead you should do + @code static const char * const weekdays[] = { wxTRANSLATE("Mon"), ..., wxTRANSLATE("Sun") }; @@ -597,53 +577,47 @@ size_t n) /* implementation is private */ @endcode here. - Note that although the code @b would compile if you simply omit wxTRANSLATE() in the above, it wouldn't work as expected because there would be no translations for the weekday names in the program message catalog and wxGetTranslation wouldn't find them. */ -#define const wxChar * wxTRANSLATE(const char * s) /* implementation is private */ +#define const wxChar* wxTRANSLATE(const char* s) /* implementation is private */ /** This macro expands into a call to wxGetTranslation function, so it marks the message for the extraction by @c xgettext just as wxTRANSLATE does, but also returns the translation of the string for the current locale during execution. - Don't confuse this macro with _T! */ -#define const wxString _(const wxString& s) /* implementation is private */ +const wxString _(const wxString& s); //@{ /** - This function returns the translation of string @e str in the current + This function returns the translation of string @a str in the current locale. If the string is not found in any of the loaded message catalogs (see @ref overview_internationalization "internationalization overview"), the original string is returned. In debug build, an error message is logged -- this should help to find the strings which were not yet translated. If - @e domain is specified then only that domain/catalog is searched + @a domain is specified then only that domain/catalog is searched for a matching string. As this function is used very often, an alternative (and also common in Unix world) syntax is provided: the _ macro is defined to do the same thing as wxGetTranslation. - The second form is used when retrieving translation of string that has different singular and plural form in English or different plural forms in some other language. It takes two extra arguments: as above, @e str parameter must contain the singular form of the string to be converted and - is used as the key for the search in the catalog. The @e strPlural parameter - is the plural form (in English). The parameter @e n is used to determine the - plural form. If no message catalog is found @e str is returned if 'n == 1', + is used as the key for the search in the catalog. The @a strPlural parameter + is the plural form (in English). The parameter @a n is used to determine the + plural form. If no message catalog is found @a str is returned if 'n == 1', otherwise @e strPlural. - See GNU gettext manual for additional information on plural forms handling. For a shorter alternative see the wxPLURAL macro. - Both versions call wxLocale::GetString. - Note that this function is not suitable for literal strings in Unicode builds, since the literal strings must be enclosed into _T or wxT macro which makes them diff --git a/interface/ipc.h b/interface/ipc.h index b878a1912d..811564e9e4 100644 --- a/interface/ipc.h +++ b/interface/ipc.h @@ -46,7 +46,6 @@ public: and/or wxClient::OnMakeConnection members should be replaced by functions which construct the new connection object. - If the arguments of the wxConnection constructor are void then the wxConnection object manages its own connection buffer, allocating memory as needed. A programmer-supplied buffer cannot @@ -144,7 +143,7 @@ public: */ virtual const void* OnRequest(const wxString& topic, const wxString& item, - size_t * size, + size_t* size, wxIPCFormat format); /** @@ -171,7 +170,6 @@ public: server connection's OnPoke() member to be called. If size is -1 the size is computed from the string length of data. - Returns @true if successful. */ bool Poke(const wxString& item, const void* data, size_t size, @@ -186,12 +184,11 @@ public: Causes the server connection's OnRequest() member to be called. Size may be @NULL or a pointer to a variable to receive the size of the requested item. - Returns a character string (actually a pointer to the connection's buffer) if successful, @NULL otherwise. This buffer does not need to be deleted. */ - const void* Request(const wxString& item, size_t * size, + const void* Request(const wxString& item, size_t* size, wxIPCFormat format = wxIPC_TEXT); /** @@ -258,34 +255,31 @@ public: overriding the OnMakeConnection() member to return your own derived connection object. - Under Unix, the service name may be either an integer port identifier in which case an Internet domain socket will be used for the communications, or a valid file name (which shouldn't exist and will be deleted afterwards) in which case a Unix domain socket is created. - @b SECURITY NOTE: Using Internet domain sockets if extremely insecure for IPC as there is absolutely no access control for them, use Unix domain sockets whenever possible! */ - wxConnectionBase * MakeConnection(const wxString& host, - const wxString& service, - const wxString& topic); + wxConnectionBase* MakeConnection(const wxString& host, + const wxString& service, + const wxString& topic); /** Called by MakeConnection(), by default this simply returns a new wxConnection object. Override this method to return a wxConnection descendant customised for the application. - The advantage of deriving your own connection class is that it will enable you to intercept messages initiated by the server, such as wxConnection::OnAdvise. You may also want to store application-specific data in instances of the new class. */ - wxConnectionBase * OnMakeConnection(); + wxConnectionBase* OnMakeConnection(); /** Returns @true if this is a valid host name, @false otherwise. This always @@ -346,12 +340,11 @@ public: member to intercept this message and return a connection object of either the standard wxConnection type, or (more likely) of a user-derived type. - If the topic is @b STDIO, the application may wish to refuse the connection. Under UNIX, when a server is created the OnAcceptConnection message is always sent for standard input and output, but in the context of DDE messages it doesn't make a lot of sense. */ - virtual wxConnectionBase * OnAcceptConnection(const wxString& topic); + virtual wxConnectionBase* OnAcceptConnection(const wxString& topic); }; diff --git a/interface/joystick.h b/interface/joystick.h index 9ed0ccff35..4d9d290adc 100644 --- a/interface/joystick.h +++ b/interface/joystick.h @@ -22,7 +22,7 @@ class wxJoystick : public wxObject { public: /** - Constructor. @e joystick may be one of wxJOYSTICK1, wxJOYSTICK2, indicating the + Constructor. @a joystick may be one of wxJOYSTICK1, wxJOYSTICK2, indicating the joystick controller of interest. */ @@ -38,7 +38,7 @@ public: Returns the state of the specified joystick button. @param id - The button id to report, from 0 to GetNumberButtons() - 1 + The button id to report, from 0 to GetNumberButtons() - 1 */ int GetButtonState(); bool GetButtonState(unsigned id); @@ -101,7 +101,7 @@ public: Returns the position of the specified joystick axis. @param axis - The joystick axis to report, from 0 to GetNumberAxes() - 1. + The joystick axis to report, from 0 to GetNumberAxes() - 1. */ wxPoint GetPosition(); int GetPosition(unsigned axis); @@ -200,7 +200,7 @@ public: /** Returns @true if the joystick has a point of view control. */ -#define bool HasPOV() /* implementation is private */ + bool HasPOV(); /** Returns @true if the joystick point-of-view supports discrete values (centered, @@ -221,29 +221,29 @@ public: /** Returns @true if the joystick has a U axis. */ -#define bool HasU() /* implementation is private */ + bool HasU(); /** Returns @true if the joystick has a V axis. */ -#define bool HasV() /* implementation is private */ + bool HasV(); /** Returns @true if the joystick has a Z axis. */ -#define bool HasZ() /* implementation is private */ + bool HasZ(); /** Returns @true if the joystick is functioning. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** Releases the capture set by @b SetCapture. @returns @true if the capture release succeeded. - @sa SetCapture(), wxJoystickEvent + @see SetCapture(), wxJoystickEvent */ bool ReleaseCapture(); @@ -251,16 +251,15 @@ public: Sets the capture to direct joystick events to @e win. @param win - The window that will receive joystick events. - + The window that will receive joystick events. @param pollingFreq - If zero, movement events are sent when above the - threshold. If greater than zero, events are received every pollingFreq + If zero, movement events are sent when above the + threshold. If greater than zero, events are received every pollingFreq milliseconds. @returns @true if the capture succeeded. - @sa ReleaseCapture(), wxJoystickEvent + @see ReleaseCapture(), wxJoystickEvent */ bool SetCapture(wxWindow* win, int pollingFreq = 0); diff --git a/interface/layout.h b/interface/layout.h index 374fa67584..2ff6b2d3f2 100644 --- a/interface/layout.h +++ b/interface/layout.h @@ -37,7 +37,7 @@ public: optional margin. Implicitly, this is relative to the top edge of the other window. */ - void Above(wxWindow * otherWin, int margin = 0); + void Above(wxWindow* otherWin, int margin = 0); /** Constrains this edge or dimension to be the given absolute value. @@ -52,14 +52,14 @@ public: to have a default size, such as a button, which may take its size from the size of the button label. */ -#define void AsIs() /* implementation is private */ + void AsIs(); /** Constrains this edge to be below the given window, with an optional margin. Implicitly, this is relative to the bottom edge of the other window. */ - void Below(wxWindow * otherWin, int margin = 0); + void Below(wxWindow* otherWin, int margin = 0); /** The @e wxEdge enumerated type specifies the type of edge or dimension of a @@ -67,32 +67,26 @@ public: wxLeft - The left edge. wxTop - The top edge. wxRight - The right edge. wxBottom - The bottom edge. wxCentreX - The x-coordinate of the centre of the window. wxCentreY - The y-coordinate of the centre of the window. The @e wxRelationship enumerated type specifies the relationship that @@ -104,49 +98,40 @@ public: wxUnconstrained - The edge or dimension is unconstrained (the default for edges. wxAsIs - The edge or dimension is to be taken from the current window position or size (the default for dimensions. wxAbove - The edge should be above another edge. wxBelow - The edge should be below another edge. wxLeftOf - The edge should be to the left of another edge. wxRightOf - The edge should be to the right of another edge. wxSameAs - The edge or dimension should be the same as another edge or dimension. wxPercentOf - The edge or dimension should be a percentage of another edge or dimension. wxAbsolute - The edge or dimension should be a given absolute value. */ @@ -156,36 +141,36 @@ public: optional margin. Implicitly, this is relative to the left edge of the other window. */ - void LeftOf(wxWindow * otherWin, int margin = 0); + void LeftOf(wxWindow* otherWin, int margin = 0); /** Constrains this edge or dimension to be to a percentage of the given window, with an optional margin. */ - void PercentOf(wxWindow * otherWin, wxEdge edge, int per); + void PercentOf(wxWindow* otherWin, wxEdge edge, int per); /** Constrains this edge to be to the right of the given window, with an optional margin. Implicitly, this is relative to the right edge of the other window. */ - void RightOf(wxWindow * otherWin, int margin = 0); + void RightOf(wxWindow* otherWin, int margin = 0); /** Constrains this edge or dimension to be to the same as the edge of the given window, with an optional margin. */ - void SameAs(wxWindow * otherWin, wxEdge edge, int margin = 0); + void SameAs(wxWindow* otherWin, wxEdge edge, int margin = 0); /** Sets the properties of the constraint. Normally called by one of the convenience functions such as Above, RightOf, SameAs. */ -#define void Set(wxRelationship rel, wxWindow * otherWin, - wxEdge otherEdge, int value = 0, - int margin = 0) /* implementation is private */ + void Set(wxRelationship rel, wxWindow* otherWin, + wxEdge otherEdge, int value = 0, + int margin = 0); /** Sets this edge or dimension to be unconstrained, that is, dependent on @@ -253,56 +238,48 @@ public: /** wxIndividualLayoutConstraint bottom - Constraint for the bottom edge. */ /** wxIndividualLayoutConstraint centreX - Constraint for the horizontal centre point. */ /** wxIndividualLayoutConstraint centreY - Constraint for the vertical centre point. */ /** wxIndividualLayoutConstraint height - Constraint for the height. */ /** wxIndividualLayoutConstraint left - Constraint for the left-hand edge. */ /** wxIndividualLayoutConstraint right - Constraint for the right-hand edge. */ /** wxIndividualLayoutConstraint top - Constraint for the top edge. */ /** wxIndividualLayoutConstraint width - Constraint for the width. */ }; diff --git a/interface/laywin.h b/interface/laywin.h index 6bbf2fe9e5..badf50f30d 100644 --- a/interface/laywin.h +++ b/interface/laywin.h @@ -91,8 +91,7 @@ @category{winlayout} @seealso - wxSashEvent, wxSashLayoutWindow, @ref overview_eventhandlingoverview "Event - handling overview" + wxSashEvent, wxSashLayoutWindow, @ref overview_eventhandlingoverview */ class wxLayoutAlgorithm : public wxObject { @@ -108,26 +107,23 @@ public: ~wxLayoutAlgorithm(); /** - Lays out the children of a normal frame. @e mainWindow is set to occupy the + Lays out the children of a normal frame. @a mainWindow is set to occupy the remaining space. - This function simply calls LayoutWindow(). */ - bool LayoutFrame(wxFrame* frame, wxWindow* mainWindow = @NULL); + bool LayoutFrame(wxFrame* frame, wxWindow* mainWindow = NULL); /** - Lays out the children of an MDI parent frame. If @e rect is non-@NULL, the + Lays out the children of an MDI parent frame. If @a rect is non-@NULL, the given rectangle will be used as a starting point instead of the frame's client area. - The MDI client window is set to occupy the remaining space. */ - bool LayoutMDIFrame(wxMDIParentFrame* frame, wxRect* rect = @NULL); + bool LayoutMDIFrame(wxMDIParentFrame* frame, wxRect* rect = NULL); /** Lays out the children of a normal frame or other window. - - @e mainWindow is set to occupy the remaining space. If this is not specified, + @a mainWindow is set to occupy the remaining space. If this is not specified, then the last window that responds to a calculate layout event in query mode will get the remaining space @@ -135,7 +131,7 @@ public: and the window will be set to the remaining size). */ - bool LayoutWindow(wxWindow* parent, wxWindow* mainWindow = @NULL); + bool LayoutWindow(wxWindow* parent, wxWindow* mainWindow = NULL); }; @@ -157,8 +153,7 @@ public: @category{miscwnd} @seealso - wxLayoutAlgorithm, wxSashWindow, @ref overview_eventhandlingoverview "Event - handling overview" + wxLayoutAlgorithm, wxSashWindow, @ref overview_eventhandlingoverview */ class wxSashLayoutWindow : public wxSashWindow { @@ -169,33 +164,29 @@ public: other non-control window. @param parent - Pointer to a parent window. - + Pointer to a parent window. @param id - Window identifier. If -1, will automatically create an identifier. - + Window identifier. If -1, will automatically create an identifier. @param pos - Window position. wxDefaultPosition is (-1, -1) which indicates that + Window position. wxDefaultPosition is (-1, -1) which indicates that wxSashLayoutWindows - should generate a default position for the window. If using the + should generate a default position for the window. If using the wxSashLayoutWindow class directly, supply - an actual position. - + an actual position. @param size - Window size. wxDefaultSize is (-1, -1) which indicates that wxSashLayoutWindows - should generate a default size for the window. - + Window size. wxDefaultSize is (-1, -1) which indicates that + wxSashLayoutWindows + should generate a default size for the window. @param style - Window style. For window styles, please see wxSashLayoutWindow. - + Window style. For window styles, please see wxSashLayoutWindow. @param name - Window name. + Window name. */ wxSashLayoutWindow(); wxSashLayoutWindow(wxSashLayoutWindow* parent, wxWindowID id, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, - long style = wxCLIP_CHILDREN | wxSW_3D, + long style = wxCLIP_CHILDREN | wxSW_3D, const wxString& name = "layoutWindow"); //@} @@ -204,32 +195,28 @@ public: any other non-control window. @param parent - Pointer to a parent window. - + Pointer to a parent window. @param id - Window identifier. If -1, will automatically create an identifier. - + Window identifier. If -1, will automatically create an identifier. @param pos - Window position. wxDefaultPosition is (-1, -1) which indicates that + Window position. wxDefaultPosition is (-1, -1) which indicates that wxSashLayoutWindows - should generate a default position for the window. If using the + should generate a default position for the window. If using the wxSashLayoutWindow class directly, supply - an actual position. - + an actual position. @param size - Window size. wxDefaultSize is (-1, -1) which indicates that wxSashLayoutWindows - should generate a default size for the window. - + Window size. wxDefaultSize is (-1, -1) which indicates that + wxSashLayoutWindows + should generate a default size for the window. @param style - Window style. For window styles, please see wxSashLayoutWindow. - + Window style. For window styles, please see wxSashLayoutWindow. @param name - Window name. + Window name. */ bool Create(wxSashLayoutWindow* parent, wxWindowID id, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, - long style = wxCLIP_CHILDREN | wxSW_3D, + long style = wxCLIP_CHILDREN | wxSW_3D, const wxString& name = "layoutWindow"); /** @@ -266,7 +253,7 @@ public: /** Sets the alignment of the window (which edge of the available parent client area the window - is attached to). @e alignment is one of wxLAYOUT_TOP, wxLAYOUT_LEFT, + is attached to). @a alignment is one of wxLAYOUT_TOP, wxLAYOUT_LEFT, wxLAYOUT_RIGHT, wxLAYOUT_BOTTOM. */ void SetAlignment(wxLayoutAlignment alignment); @@ -282,7 +269,7 @@ public: /** Sets the orientation of the window (the direction the window will stretch in, to fill the available - parent client area). @e orientation is one of wxLAYOUT_HORIZONTAL, + parent client area). @a orientation is one of wxLAYOUT_HORIZONTAL, wxLAYOUT_VERTICAL. */ void SetOrientation(wxLayoutOrientation orientation); diff --git a/interface/link.h b/interface/link.h index 34fa33b14e..5cf6774bc9 100644 --- a/interface/link.h +++ b/interface/link.h @@ -10,7 +10,6 @@ This macro can be used in conjunction with the wxFORCE_LINK_MODULE macro to force the linker to include in its output a specific object file. - In particular, you should use this macro in the source file which you want to force for inclusion. The @c moduleName needs to be a name not already in use in other @c wxFORCE_LINK_THIS_MODULE macros, but is not required @@ -23,7 +22,6 @@ to be e.g. the same name of the source file (even if it's a good choice). This macro can be used in conjunction with the wxFORCE_LINK_THIS_MODULE macro to force the linker to include in its output a specific object file. - In particular, you should use this macro in a source file which you know for sure is linked in the output (e.g. the source file containing the "main()" of your app). The @c moduleName is the name of the module you want to diff --git a/interface/list.h b/interface/list.h index 679bff3e46..7ec8119bb2 100644 --- a/interface/list.h +++ b/interface/list.h @@ -48,7 +48,7 @@ public: Constructors. */ wxListT(); - wxListT(size_t count, T * elements[]); + wxListT(size_t count, T* elements[]); //@} /** @@ -58,9 +58,9 @@ public: ~wxListT(); /** - Appends the pointer to @e object to the list. + Appends the pointer to @a object to the list. */ - wxListT::compatibility_iterator Append(T * object); + wxListT::compatibility_iterator Append(T* object); /** Clears the list, but does not delete the objects stored in the list @@ -69,7 +69,7 @@ public: void Clear(); /** - If @e destroy is @true, instructs the list to call @e delete + If @a destroy is @true, instructs the list to call @e delete on objects stored in the list whenever they are removed. The default is @false. */ @@ -82,11 +82,11 @@ public: bool DeleteNode(const compatibility_iterator& iter); /** - Finds the given @e object and removes it from the list, returning + Finds the given @a object and removes it from the list, returning @true if successful. The application must delete the actual object separately. */ - bool DeleteObject(T * object); + bool DeleteObject(T* object); /** Removes element refered to be @c iter. @@ -94,9 +94,9 @@ public: void Erase(const compatibility_iterator& iter); /** - Returns the iterator refering to @e object or @NULL if none found. + Returns the iterator refering to @a object or @NULL if none found. */ - wxListT::compatibility_iterator Find(T * object); + wxListT::compatibility_iterator Find(T* object); /** Returns the number of elements in the list. @@ -114,8 +114,8 @@ public: wxListT::compatibility_iterator GetLast(); /** - Returns the index of @e obj within the list or @c wxNOT_FOUND if - @e obj is not found in the list. + Returns the index of @a obj within the list or @c wxNOT_FOUND if + @a obj is not found in the list. */ int IndexOf(T* obj); @@ -123,11 +123,11 @@ public: /** Inserts the object before the object refered to be @e iter. */ - wxListT::compatibility_iterator Insert(T * object); + wxListT::compatibility_iterator Insert(T* object); wxListT::compatibility_iterator Insert(size_t position, - T * object); + T* object); wxListT::compatibility_iterator Insert(compatibility_iterator iter, - T * object); + T* object); //@} /** @@ -144,20 +144,18 @@ public: /** @b NB: This function is deprecated, use wxList::Find instead. */ - wxListT::compatibility_iterator Member(T * object); + wxListT::compatibility_iterator Member(T* object); /** @b NB: 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). */ -#define wxListT::compatibility_iterator Nth(int n) /* implementation is private */ + wxListT::compatibility_iterator Nth(int n); /** @b NB: This function is deprecated, use wxList::GetCount instead. - Returns the number of elements in the list. */ int Number(); @@ -213,7 +211,7 @@ public: //@{ /** - Erases the items from @e first to @e last. + Erases the items from @a first to @e last. */ iterator erase(const iterator& it); iterator erase(const iterator& first, @@ -255,14 +253,12 @@ public: /** ) - Adds an item to end of the list. */ void push_back(); /** ) - Adds an item to the front of the list. */ void push_front(); @@ -292,7 +288,6 @@ public: /** ) - Resizes the list. If the the list is enlarges items with the value @e v are appended to the list. */ @@ -341,17 +336,17 @@ public: /** Retrieves the client data pointer associated with the node. */ - T * GetData(); + T* GetData(); /** Retrieves the next node or @NULL if this node is the last one. */ - wxNodeT * GetNext(); + wxNodeT* GetNext(); /** Retrieves the previous node or @NULL if this node is the first one in the list. */ - wxNodeT * GetPrevious(); + wxNodeT* GetPrevious(); /** Returns the zero-based index of this node within the list. The return value @@ -363,5 +358,5 @@ public: Sets the data associated with the node (usually the pointer will have been set when the node was created). */ - void SetData(T * data); + void SetData(T* data); }; diff --git a/interface/listbox.h b/interface/listbox.h index 7c1ab8e1d4..3d8271a3b0 100644 --- a/interface/listbox.h +++ b/interface/listbox.h @@ -44,10 +44,10 @@ @endStyleTable @beginEventTable - @event{EVT_LISTBOX(id\, func)}: + @event{EVT_LISTBOX(id, func)}: Process a wxEVT_COMMAND_LISTBOX_SELECTED event, when an item on the list is selected or the selection changes. - @event{EVT_LISTBOX_DCLICK(id\, func)}: + @event{EVT_LISTBOX_DCLICK(id, func)}: Process a wxEVT_COMMAND_LISTBOX_DOUBLECLICKED event, when the listbox is double-clicked. @endEventTable @@ -67,41 +67,34 @@ public: Constructor, creating and showing a list box. @param parent - Parent window. Must not be @NULL. - + Parent window. Must not be @NULL. @param id - Window identifier. The value wxID_ANY indicates a default value. - + Window identifier. The value wxID_ANY indicates a default value. @param pos - Window position. - + Window position. @param size - Window size. If wxDefaultSize is specified then the window is sized - appropriately. - + Window size. If wxDefaultSize is specified then the window is + sized + appropriately. @param n - Number of strings with which to initialise the control. - + Number of strings with which to initialise the control. @param choices - An array of strings with which to initialise the control. - + An array of strings with which to initialise the control. @param style - Window style. See wxListBox. - + Window style. See wxListBox. @param validator - Window validator. - + Window validator. @param name - Window name. + Window name. - @sa Create(), wxValidator + @see Create(), wxValidator */ wxListBox(); wxListBox(wxWindow* parent, wxWindowID id, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, int n = 0, - const wxString choices[] = @NULL, + const wxString choices[] = NULL, long style = 0, const wxValidator& validator = wxDefaultValidator, const wxString& name = "listBox"); @@ -128,7 +121,7 @@ public: const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, int n, - const wxString choices[] = @NULL, + const wxString choices[] = NULL, long style = 0, const wxValidator& validator = wxDefaultValidator, const wxString& name = "listBox"); @@ -145,7 +138,7 @@ public: Deselects an item in the list box. @param n - The zero-based item to deselect. + The zero-based item to deselect. @remarks This applies to multiple selection listboxes only. */ @@ -155,31 +148,30 @@ public: Fill an array of ints with the positions of the currently selected items. @param selections - A reference to an wxArrayInt instance that is used to store the result of the - query. + A reference to an wxArrayInt instance that is used to store the result of + the query. @returns The number of selections. @remarks Use this with a multiple selection listbox. - @sa wxControlWithItems::GetSelection, wxControlWithItems::GetStringSelection, - wxControlWithItems::SetSelection + @see wxControlWithItems::GetSelection, wxControlWithItems::GetStringSelection, + wxControlWithItems::SetSelection */ int GetSelections(wxArrayInt& selections); /** Returns the item located at @e point, or @c wxNOT_FOUND if there is no item located at @e point. - This function is new since wxWidgets version 2.7.0. It is currently implemented for wxMSW, wxMac and wxGTK2 ports. @param point - Point of item (in client coordinates) to obtain + Point of item (in client coordinates) to obtain @returns Item located at point, or wxNOT_FOUND if unimplemented or the - item does not exist. + item does not exist. */ int HitTest(const wxPoint point); @@ -188,14 +180,13 @@ public: Insert the given number of strings before the specified position. @param nItems - Number of items in the array items - + Number of items in the array items @param items - Labels of items to be inserted - + Labels of items to be inserted @param pos - Position before which to insert the items: for example, if pos is 0 the items - will be inserted in the beginning of the listbox + Position before which to insert the items: for example, if pos is 0 the + items + will be inserted in the beginning of the listbox */ void InsertItems(int nItems, const wxString items, unsigned int pos); @@ -207,7 +198,7 @@ public: Determines whether an item is selected. @param n - The zero-based item index. + The zero-based item index. @returns @true if the given item is selected, @false otherwise. */ @@ -218,20 +209,18 @@ public: Clears the list box and adds the given strings to it. @param n - The number of strings to set. - + The number of strings to set. @param choices - An array of strings to set. - + An array of strings to set. @param clientData - Options array of client data pointers + Options array of client data pointers @remarks You may free the array from the calling program after this - function has been called. + function has been called. */ - void Set(int n, const wxString* choices, void clientData = @NULL); + void Set(int n, const wxString* choices, void clientData = NULL); void Set(const wxArrayString& choices, - void clientData = @NULL); + void clientData = NULL); //@} //@{ @@ -239,10 +228,9 @@ public: Set the specified item to be the first visible item. @param n - The zero-based item index. - + The zero-based item index. @param string - The string that should be visible. + The string that should be visible. */ void SetFirstItem(int n); void SetFirstItem(const wxString& string); diff --git a/interface/listctrl.h b/interface/listctrl.h index d020d7516d..5a1a186d93 100644 --- a/interface/listctrl.h +++ b/interface/listctrl.h @@ -98,28 +98,23 @@ public: Constructor, creating and showing a list control. @param parent - Parent window. Must not be @NULL. - + Parent window. Must not be @NULL. @param id - Window identifier. The value wxID_ANY indicates a default value. - + Window identifier. The value wxID_ANY indicates a default value. @param pos - Window position. - + Window position. @param size - Window size. If wxDefaultSize is specified then the window is sized - appropriately. - + Window size. If wxDefaultSize is specified then the window is + sized + appropriately. @param style - Window style. See wxListCtrl. - + Window style. See wxListCtrl. @param validator - Window validator. - + Window validator. @param name - Window name. + Window name. - @sa Create(), wxValidator + @see Create(), wxValidator */ wxListCtrl(); wxListCtrl(wxWindow* parent, wxWindowID id, @@ -137,27 +132,22 @@ public: /** Arranges the items in icon or small icon view. This only has effect on Win32. - @e flag is one of: - + @a flag is one of: wxLIST_ALIGN_DEFAULT - Default alignment. wxLIST_ALIGN_LEFT - Align to the left side of the control. wxLIST_ALIGN_TOP - Align to the top side of the control. wxLIST_ALIGN_SNAP_TO_GRID - Snap to grid. */ bool Arrange(int flag = wxLIST_ALIGN_DEFAULT); @@ -165,11 +155,11 @@ public: /** Sets the image list associated with the control and takes ownership of it (i.e. the control will, unlike when using - SetImageList, delete the list when destroyed). @e which is one of + SetImageList, delete the list when destroyed). @a which is one of wxIMAGE_LIST_NORMAL, wxIMAGE_LIST_SMALL, wxIMAGE_LIST_STATE (the last is unimplemented). - @sa SetImageList() + @see SetImageList() */ void AssignImageList(wxImageList* imageList, int which); @@ -190,7 +180,6 @@ public: /** Deletes all items in the list control. - @b NB: 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). @@ -205,7 +194,6 @@ public: /** Deletes the specified item. This function sends the @c wxEVT_COMMAND_LIST_DELETE_ITEM event for the item being deleted. - See also: DeleteAllItems() */ bool DeleteItem(long item); @@ -214,7 +202,6 @@ public: Starts editing the label of the given item. This function generates a EVT_LIST_BEGIN_LABEL_EDIT event which can be vetoed so that no text control will appear for in-place editing. - If the user changed the label (i.e. s/he does not press ESC or leave the text control without changes, a EVT_LIST_END_LABEL_EDIT event will be sent which can be vetoed as well. @@ -229,22 +216,19 @@ public: //@{ /** Find an item nearest this position in the specified direction, starting from - @e start or the beginning if @e start is -1. - + @a start or the beginning if @a start is -1. @b FindItem( start, str, partial = @false ) - @b FindItemData( start, data ) - @b FindItemAtPos( start, point, direction ) */ long FindItem(long start, const wxString& str, - bool partial = @false); + bool partial = false); long FindItem(long start, long data); long FindItem(long start, const wxPoint& pt, int direction); //@} @@ -292,29 +276,24 @@ 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, not for the native Mac OS X version. */ - wxTextCtrl * GetEditControl(); + wxTextCtrl* GetEditControl(); /** - Returns the specified image list. @e which may be one of: - + Returns the specified image list. @a which may be one of: @b wxIMAGE_LIST_NORMAL - The normal (large icon) image list. @b wxIMAGE_LIST_SMALL - The small icon image list. @b wxIMAGE_LIST_STATE - The user-defined state image list (unimplemented). */ wxImageList* GetImageList(int which); @@ -322,7 +301,6 @@ public: /** Gets information about the item. See SetItem() for more information. - You must call @e info.SetId() to the ID of item you're interested in before calling this method. */ @@ -333,7 +311,7 @@ public: an invalid colour (and not the default background control of the control itself). - @sa GetItemTextColour() + @see GetItemTextColour() */ wxColour GetItemBackgroundColour(long item); @@ -360,8 +338,7 @@ public: /** Returns the rectangle representing the item's size and position, in physical coordinates. - - @e code is one of wxLIST_RECT_BOUNDS, wxLIST_RECT_ICON, wxLIST_RECT_LABEL. + @a code is one of wxLIST_RECT_BOUNDS, wxLIST_RECT_ICON, wxLIST_RECT_LABEL. */ bool GetItemRect(long item, wxRect& rect, int code = wxLIST_RECT_BOUNDS); @@ -375,7 +352,6 @@ public: /** Gets the item state. For a list of state flags, see SetItem(). - The @b stateMask indicates which state flags are of interest. */ int GetItemState(long item, long stateMask); @@ -396,70 +372,56 @@ public: /** Searches for an item with the given geometry or state, starting from - @e item but excluding the @e item itself. If @e item is -1, + @a item but excluding the @a item itself. If @a item is -1, the first item that matches the specified flags will be returned. - - Returns the first item with given state following @e item or -1 if + Returns the first item with given state following @a item or -1 if no such item found. - This function may be used to find all selected items in the control like this: - @e geometry can be one of: + @a geometry can be one of: wxLIST_NEXT_ABOVE - Searches for an item above the specified item. wxLIST_NEXT_ALL - Searches for subsequent item by index. wxLIST_NEXT_BELOW - Searches for an item below the specified item. wxLIST_NEXT_LEFT - Searches for an item to the left of the specified item. wxLIST_NEXT_RIGHT - Searches for an item to the right of the specified item. @b NB: this parameter is only supported by wxMSW currently and ignored on other platforms. - - @e state can be a bitlist of the following: - + @a state can be a bitlist of the following: wxLIST_STATE_DONTCARE - Don't care what the state is. wxLIST_STATE_DROPHILITED - The item indicates it is a drop target. wxLIST_STATE_FOCUSED - The item has the focus. wxLIST_STATE_SELECTED - The item is selected. wxLIST_STATE_CUT - The item is selected as part of a cut and paste operation. */ long GetNextItem(long item, int geometry = wxLIST_NEXT_ALL, @@ -472,17 +434,14 @@ public: /** Returns the rectangle representing the size and position, in physical - coordinates, of the given subitem, i.e. the part of the row @e item in the + coordinates, of the given subitem, i.e. the part of the row @a item in the column @e subItem. - This method is only meaningfull when the wxListCtrl is in the report mode. If - @e subItem parameter is equal to the special value + @a subItem parameter is equal to the special value @c wxLIST_GETSUBITEMRECT_WHOLEITEM the return value is the same as for GetItemRect(). - - @e code can be one of @c wxLIST_RECT_BOUNDS, + @a code can be one of @c wxLIST_RECT_BOUNDS, @c wxLIST_RECT_ICON or @c wxLIST_RECT_LABEL. - This function is new since wxWidgets version 2.7.0 */ bool GetSubItemRect(long item, long subItem, wxRect& rect, @@ -503,7 +462,6 @@ public: Returns the rectangle taken by all items in the control. In other words, if the controls client size were equal to the size of this rectangle, no scrollbars would be needed and no free space would be left. - Note that this function only works in the icon and small icon views, not in list or report views (this is a limitation of the native Win32 control). */ @@ -513,70 +471,59 @@ public: Determines which item (if any) is at the specified point, giving details in @e flags. Returns index of the item or @c wxNOT_FOUND if no item is at the specified point. - @e flags will be a combination of the following flags: - + @a flags will be a combination of the following flags: wxLIST_HITTEST_ABOVE - Above the client area. wxLIST_HITTEST_BELOW - Below the client area. wxLIST_HITTEST_NOWHERE - In the client area but below the last item. wxLIST_HITTEST_ONITEMICON - On the bitmap associated with an item. wxLIST_HITTEST_ONITEMLABEL - On the label (string) associated with an item. wxLIST_HITTEST_ONITEMRIGHT - In the area to the right of an item. wxLIST_HITTEST_ONITEMSTATEICON - On the state icon for a tree view item that is in a user-defined state. wxLIST_HITTEST_TOLEFT - To the right of the client area. wxLIST_HITTEST_TORIGHT - To the left of the client area. wxLIST_HITTEST_ONITEM - Combination of wxLIST_HITTEST_ONITEMICON, wxLIST_HITTEST_ONITEMLABEL, wxLIST_HITTEST_ONITEMSTATEICON. - If @e ptrSubItem is not @NULL and the wxListCtrl is in the report + If @a ptrSubItem is not @NULL and the wxListCtrl is in the report mode the subitem (or column) number will also be provided. This feature is only available in version 2.7.0 or higher and is currently only implemented under wxMSW and requires at least comctl32.dll of verion 4.70 on - the host system or the value stored in @e ptrSubItem will be always -1. To + the host system or the value stored in @a ptrSubItem will be always -1. To compile this feature into wxWidgets library you need to have access to commctrl.h of version 4.70 that is provided by Microsoft. */ long HitTest(const wxPoint& point, int& flags, - long * ptrSubItem); + long* ptrSubItem); //@{ /** @@ -593,16 +540,13 @@ public: Insert an image/string item. @param info - wxListItem object - + wxListItem object @param index - Index of the new item, supplied by the application - + Index of the new item, supplied by the application @param label - String label - + String label @param imageIndex - index into the image list associated with this control and view style + index into the image list associated with this control and view style */ long InsertItem(wxListItem& info); long InsertItem(long index, const wxString& label); @@ -616,27 +560,24 @@ public: @c wxLC_VIRTUAL style. It should return the attribute for the for the specified @c item or @NULL to use the default appearance parameters. - wxListCtrl will not delete the pointer or keep a reference of it. You can return the same wxListItemAttr pointer for every OnGetItemAttr call. - The base class version always returns @NULL. - @sa OnGetItemImage(), OnGetItemColumnImage(), - OnGetItemText() + @see OnGetItemImage(), OnGetItemColumnImage(), + OnGetItemText() */ - virtual wxListItemAttr * OnGetItemAttr(long item); + virtual wxListItemAttr* OnGetItemAttr(long item); /** Overload this function in the derived class for a control with @c wxLC_VIRTUAL and @c wxLC_REPORT styles in order to specify the image index for the given line and column. - The base class version always calls OnGetItemImage for the first column, else it returns -1. - @sa OnGetItemText(), OnGetItemImage(), - OnGetItemAttr() + @see OnGetItemText(), OnGetItemImage(), + OnGetItemAttr() */ virtual int OnGetItemColumnImage(long item, long column); @@ -648,21 +589,20 @@ public: or -1 for no image. In a control with @c wxLC_REPORT style, OnGetItemImage only gets called for the first column of each line. - The base class version always returns -1. - @sa OnGetItemText(), OnGetItemColumnImage(), - OnGetItemAttr() + @see OnGetItemText(), OnGetItemColumnImage(), + OnGetItemAttr() */ virtual int OnGetItemImage(long item); /** This function @b must be overloaded in the derived class for a control with @c wxLC_VIRTUAL style. It should return the string containing the text of - the given @e column for the specified @c item. + the given @a column for the specified @c item. - @sa SetItemCount(), OnGetItemImage(), - OnGetItemColumnImage(), OnGetItemAttr() + @see SetItemCount(), OnGetItemImage(), + OnGetItemColumnImage(), OnGetItemAttr() */ virtual wxString OnGetItemText(long item, long column); @@ -671,14 +611,13 @@ public: as without calling this function the displayed value of the item doesn't change even when the underlying data does change. - @sa RefreshItems() + @see RefreshItems() */ void RefreshItem(long item); /** - Redraws the items between @e itemFrom and @e itemTo. The starting item + Redraws the items between @a itemFrom and @e itemTo. The starting item must be less than or equal to the ending one. - Just as RefreshItem() this is only useful for virtual list controls. */ @@ -686,10 +625,9 @@ public: /** Scrolls the list control. If in icon, small icon or report view mode, - @e dx specifies the number of pixels to scroll. If in list view mode, - @e dx specifies the number of columns to scroll. @e dy always specifies + @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. */ bool ScrollList(int dx, int dy); @@ -708,37 +646,33 @@ public: /** Sets the column width. - - @e width can be a width in pixels or wxLIST_AUTOSIZE (-1) or + @a width can be a width in pixels or wxLIST_AUTOSIZE (-1) or wxLIST_AUTOSIZE_USEHEADER (-2). wxLIST_AUTOSIZE will resize the column to the length of its longest item. wxLIST_AUTOSIZE_USEHEADER will resize the column to the length of the header (Win32) or 80 pixels (other platforms). - - In small or normal icon view, @e col must be -1, and the column width is set + In small or normal icon view, @a col must be -1, and the column width is set for all columns. */ bool SetColumnWidth(int col, int width); /** - Sets the order of all columns at once. The @e orders array must have the + Sets the order of all columns at once. The @a orders array must have the same number elements as the number of columns and contain each position exactly once. - This function is valid in report view only. */ bool SetColumnOrder(const wxArrayInt& orders); /** - Sets the image list associated with the control. @e which is one of + Sets the image list associated with the control. @a which is one of wxIMAGE_LIST_NORMAL, wxIMAGE_LIST_SMALL, wxIMAGE_LIST_STATE (the last is unimplemented). - This method does not take ownership of the image list, you have to delete it yourself. - @sa AssignImageList() + @see AssignImageList() */ void SetImageList(wxImageList* imageList, int which); @@ -885,7 +819,6 @@ The m_stateMask and m_state members take flags from the following: /** Sets the background colour for this item. This function only works in report view. - The colour can be retrieved using GetItemBackgroundColour(). */ @@ -909,7 +842,6 @@ The m_stateMask and m_state members take flags from the following: /** Associates application-defined data with this item. - Notice that this function cannot be used to associate pointers with the control items, use SetItemPtrData() instead. */ @@ -924,7 +856,7 @@ The m_stateMask and m_state members take flags from the following: /** Sets the unselected and selected images associated with the item. The images are indices into the - image list associated with the list control. This form is deprecated: @e + image list associated with the list control. This form is deprecated: @a selImage is not used. */ @@ -938,18 +870,16 @@ The m_stateMask and m_state members take flags from the following: bool SetItemPosition(long item, const wxPoint& pos); /** - Associates application-defined data with this item. The @e data parameter may + Associates application-defined data with this item. The @a data parameter may be either an integer or a pointer cast to the @c wxUIntPtr type which is guaranteed to be large enough to be able to contain all integer types and pointers. - This function is new since wxWidgets version 2.8.4 */ bool SetItemPtrData(long item, wxUIntPtr data); /** Sets the item state. For a list of state flags, see SetItem(). - The @b stateMask indicates which state flags are valid. */ bool SetItemState(long item, long state, long stateMask); @@ -961,7 +891,6 @@ The m_stateMask and m_state members take flags from the following: /** Sets the colour for this item. This function only works in report view. - The colour can be retrieved using GetItemTextColour(). */ @@ -970,7 +899,7 @@ The m_stateMask and m_state members take flags from the following: /** Adds or removes a single window style. */ - void SetSingleStyle(long style, bool add = @true); + void SetSingleStyle(long style, bool add = true); /** Sets the text colour of the list control. @@ -984,21 +913,20 @@ The m_stateMask and m_state members take flags from the following: /** Call this function to sort the items in the list control. Sorting is done - using the specified @e fnSortCallBack function. This function must have the + using the specified @a fnSortCallBack function. This function must have the following prototype: + It is called each time when the two items must be compared and should return 0 if the items are equal, negative value if the first item is less than the second one and positive value if the first one is greater than the second one (the same convention as used by @c qsort(3)). @param item1 - client data associated with the first item (NOT the index). - + client data associated with the first item (NOT the index). @param item2 - client data associated with the second item (NOT the index). - + client data associated with the second item (NOT the index). @param data - the value passed to SortItems() itself. + the value passed to SortItems() itself. */ bool SortItems(wxListCtrlCompare fnSortCallBack, long data); }; @@ -1203,9 +1131,9 @@ public: Resets the column image -- after calling this function, no image will be shown. @param col - the column to clear image for + the column to clear image for - @sa SetColumnImage() + @see SetColumnImage() */ void ClearColumnImage(int col); @@ -1226,7 +1154,7 @@ public: /** Returns the currently focused item or -1 if none. - @sa IsSelected(), Focus() + @see IsSelected(), Focus() */ long GetFocusedItem(); @@ -1235,15 +1163,15 @@ public: iterate over all selected items in the control. @returns Returns the next selected item or -1 if there are no more of - them. + them. */ long GetNextSelected(long item); /** - Returns @true if the item with the given @e index is selected, + Returns @true if the item with the given @a index is selected, @false otherwise. - @sa GetFirstSelected(), GetNextSelected() + @see GetFirstSelected(), GetNextSelected() */ bool IsSelected(long index); @@ -1251,24 +1179,22 @@ public: Selects or unselects the given item. @param n - the item to select or unselect - + the item to select or unselect @param on - if @true (default), selects the item, otherwise unselects it + if @true (default), selects the item, otherwise unselects it - @sa wxListCtrl::SetItemState + @see wxListCtrl::SetItemState */ - void Select(bool on = @true); + void Select(bool on = true); /** Sets the column image for the specified column. To use the column images, the control must have a valid image list with at least one image. @param col - the column to set image for - + the column to set image for @param image - the index of the column image in the controls image list + the index of the column image in the controls image list */ void SetColumnImage(int col, int image); }; @@ -1338,35 +1264,28 @@ public: Returns a bit mask indicating which fields of the structure are valid; can be any combination of the following values: - wxLIST_MASK_STATE - @b GetState is valid. wxLIST_MASK_TEXT - @b GetText is valid. wxLIST_MASK_IMAGE - @b GetImage is valid. wxLIST_MASK_DATA - @b GetData is valid. wxLIST_MASK_WIDTH - @b GetWidth is valid. wxLIST_MASK_FORMAT - @b GetFormat is valid. */ long GetMask(); @@ -1375,30 +1294,24 @@ public: Returns a bit field representing the state of the item. Can be any combination of: - wxLIST_STATE_DONTCARE - Don't care what the state is. Win32 only. wxLIST_STATE_DROPHILITED - The item is highlighted to receive a drop event. Win32 only. wxLIST_STATE_FOCUSED - The item has the focus. wxLIST_STATE_SELECTED - The item is selected. wxLIST_STATE_CUT - The item is in the cut state. Win32 only. */ long GetState(); diff --git a/interface/log.h b/interface/log.h index 065ec5137c..4e127526da 100644 --- a/interface/log.h +++ b/interface/log.h @@ -29,38 +29,34 @@ public: Creates the log frame window and starts collecting the messages in it. @param parent - The parent window for the log frame, may be @NULL - + The parent window for the log frame, may be @NULL @param title - The title for the log frame - + The title for the log frame @param show - @true to show the frame initially (default), otherwise - Show() must be called later. - + @true to show the frame initially (default), otherwise + Show() must be called later. @param passToOld - @true to process the log messages normally in addition to - logging them in the log frame (default), @false to only log them in the - log frame. + @true to process the log messages normally in addition to + logging them in the log frame (default), @false to only log them in the + log frame. */ - wxLogWindow(wxFrame parent, const wxChar title, bool show = @true, - bool passToOld = @true); + wxLogWindow(wxFrame parent, const wxChar title, bool show = true, + bool passToOld = true); /** Returns the associated log frame window. This may be used to position or resize it but use Show() to show or hide it. */ - wxFrame * GetFrame(); + wxFrame* GetFrame(); /** Called if the user closes the window interactively, will not be called if it is destroyed for another reason (such as when program exits). - Return @true from here to allow the frame to close, @false to prevent this from happening. - @sa OnFrameDelete() + @see OnFrameDelete() */ virtual bool OnFrameClose(wxFrame frame); @@ -79,7 +75,7 @@ public: /** Shows or hides the frame. */ - void Show(bool show = @true); + void Show(bool show = true); }; @@ -145,7 +141,7 @@ public: Sets the specified @c logger (which may be @NULL) as the default log target but the log messages are also passed to the previous log target if any. */ - wxLogChain(wxLog * logger); + wxLogChain(wxLog* logger); /** Destroys the previous log target. @@ -161,7 +157,7 @@ public: /** Returns the pointer to the previously active log target (which may be @NULL). */ - wxLog * GetOldLog(); + wxLog* GetOldLog(); /** Returns @true if the messages are passed to the previously active log @@ -174,7 +170,7 @@ public: By default, the log messages are passed to the previously active log target. Calling this function with @false parameter disables this behaviour (presumably temporarily, as you shouldn't use wxLogChain at all otherwise) and - it can be reenabled by calling it again with @e passMessages set to @true. + it can be reenabled by calling it again with @a passMessages set to @true. */ void PassMessages(bool passMessages); @@ -182,12 +178,11 @@ public: Sets another log target to use (may be @NULL). The log target specified in the @ref ctor() constructor or in a previous call to this function is deleted. - This doesn't change the old log target value (the one the messages are forwarded to) which still remains the same as was active when wxLogChain object was created. */ - void SetLog(wxLog * logger); + void SetLog(wxLog* logger); }; @@ -234,7 +229,7 @@ public: Constructs a log target which sends all the log messages to the given output stream. If it is @NULL, the messages are sent to @c cerr. */ - wxLogStream(std::ostream ostr = @NULL); + wxLogStream(std::ostream ostr = NULL); }; @@ -259,7 +254,7 @@ public: Constructs a log target which sends all the log messages to the given @c FILE. If it is @NULL, the messages are sent to @c stderr. */ - wxLogStderr(FILE fp = @NULL); + wxLogStderr(FILE fp = NULL); }; @@ -293,7 +288,6 @@ public: /** Returns the current buffer contains. Messages from different log function calls are separated with the new lines in the buffer. - The buffer can be cleared by Flush() which will also show the current contents to the user. */ @@ -348,7 +342,7 @@ class wxLogTextCtrl : public wxLog public: /** Constructs a log target which sends all the log messages to the given text - control. The @e textctrl parameter cannot be @NULL. + control. The @a textctrl parameter cannot be @NULL. */ wxLogTextCtrl(wxTextCtrl textctrl); }; @@ -384,10 +378,10 @@ class wxLog { public: /** - Add the @e mask to the list of allowed masks for + Add the @a mask to the list of allowed masks for wxLogTrace. - @sa RemoveTraceMask(), GetTraceMasks() + @see RemoveTraceMask(), GetTraceMasks() */ static void AddTraceMask(const wxString& mask); @@ -395,7 +389,7 @@ public: Removes all trace masks previously set with AddTraceMask(). - @sa RemoveTraceMask() + @see RemoveTraceMask() */ static void ClearTraceMasks(); @@ -403,37 +397,34 @@ public: The functions below allow some limited customization of wxLog behaviour without writing a new log target class (which, aside of being a matter of several minutes, allows you to do anything you want). - The verbose messages are the trace messages which are not disabled in the release mode and are generated by wxLogVerbose. They are not normally shown to the user because they present little interest, but may be activated, for example, in order to help the user find some program problem. - As for the (real) trace messages, their handling depends on the settings of the (application global) @e trace mask. There are two ways to specify it: either by using SetTraceMask() and GetTraceMask() and using wxLogTrace which takes an integer mask or by using AddTraceMask() for string trace masks. - The difference between bit-wise and string trace masks is that a message using integer trace mask will only be logged if all bits of the mask are set in the current mask while a message using string mask will be logged simply if the mask had been added before to the list of allowed ones. - For example, + will do something only if the current trace mask contains both @c wxTraceRefCount and @c wxTraceOle, but + will log the message if it was preceded by + Using string masks is simpler and allows to easily add custom ones, so this is the preferred way of working with trace messages. The integer trace mask is kept for compatibility and for additional (but very rarely needed) flexibility only. - The standard trace masks are given in wxLogTrace documentation. - Finally, the @e wxLog::DoLog() function automatically prepends a time stamp to all the messages. The format of the time stamp may be changed: it can be any string with % specifications fully described in the documentation of the @@ -441,13 +432,11 @@ 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 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 SetTimestamp() explicitly. - AddTraceMask() RemoveTraceMask() @@ -478,16 +467,14 @@ public: /** Disables time stamping of the log messages. - This function is new since wxWidgets version 2.9 */ void SetTimestamp(const wxString& format); /** - Called to process the message of the specified severity. @e msg is the text + Called to process the message of the specified severity. @a msg is the text of the message as specified in the call of @e wxLogXXX() function which - generated it and @e timestamp is the moment when the message was generated. - + generated it and @a timestamp is the moment when the message was generated. The base class version prepends the timestamp to the message, adds a prefix corresponding to the log level and then calls DoLogString() with the resulting string. @@ -498,7 +485,6 @@ public: /** Called to log the specified string. The timestamp is already included in the string but still passed to this function. - A simple implementation may just send the string to @c stdout or, better, @c stderr. */ @@ -508,7 +494,6 @@ public: Instructs wxLog to not create new log targets on the fly if there is none currently. (Almost) for internal use only: it is supposed to be called by the application shutdown code. - Note that this function also calls ClearTraceMasks(). */ @@ -523,14 +508,14 @@ public: /** Flushes the current log target if any, does nothing if there is none. - @sa Flush() + @see Flush() */ static void FlushActive(); /** Returns the pointer to the active log target (may be @NULL). */ - static wxLog * GetActiveTarget(); + static wxLog* GetActiveTarget(); /** Returns the current log level limit. @@ -556,7 +541,7 @@ public: /** Returns the currently allowed list of string trace masks. - @sa AddTraceMask(). + @see AddTraceMask(). */ static const wxArrayString GetTraceMasks(); @@ -574,7 +559,6 @@ public: automatic creation of a standard log target if none actually exists. It is only useful when the application is terminating and shouldn't be used in other situations because it may easily lead to a loss of messages. - OnLog() GetActiveTarget() @@ -590,9 +574,8 @@ public: /** - Returns @true if the @e mask is one of allowed masks for + Returns @true if the @a mask is one of allowed masks for wxLogTrace. - See also: AddTraceMask(), RemoveTraceMask() */ @@ -611,14 +594,12 @@ public: screen and forward the error messages to the user's (or programmer's) cell phone - maybe depending on whether the timestamp tells us if it is day or night in the current time zone). - There also functions to support message buffering. Why are they needed? Some of wxLog implementations, most notably the standard wxLogGui class, buffer the messages (for example, to avoid showing the user a zillion of modal message boxes one after another -- which would be really annoying). Flush() shows them all and clears the buffer contents. This function doesn't do anything if the buffer is already empty. - Flush() FlushActive() @@ -632,9 +613,8 @@ public: static void OnLog(wxLogLevel level, const wxString& message); /** - Remove the @e mask from the list of allowed masks for + Remove the @a mask from the list of allowed masks for wxLogTrace. - See also: AddTraceMask() */ static void RemoveTraceMask(const wxString& mask); @@ -652,7 +632,7 @@ public: instance of wxLogNull not @NULL. If the active log target is set to @NULL a new default log target will be created when logging occurs. */ - static wxLog * SetActiveTarget(wxLog * logtarget); + static wxLog* SetActiveTarget(wxLog* logtarget); /** Specifies that log messages with level logLevel should be ignored @@ -665,7 +645,7 @@ public: the same message successively repeats one or more times, only the number of repetitions is logged. */ - static void SetRepetitionCounting(bool repetCounting = @true); + static void SetRepetitionCounting(bool repetCounting = true); /** Sets the timestamp format prepended by the default log targets to all @@ -685,20 +665,19 @@ public: Activates or deactivates verbose mode in which the verbose messages are logged as the normal ones instead of being silently dropped. */ - static void SetVerbose(bool verbose = @true); + static void SetVerbose(bool verbose = true); /** Suspends the logging until Resume() is called. Note that the latter must be called the same number of times as the former to undo it, i.e. if you call Suspend() twice you must call Resume() twice as well. - Note that suspending the logging means that the log sink won't be be flushed periodically, it doesn't have any effect if the current log target does the logging immediately without waiting for Flush() to be called (the standard GUI log target only shows the log dialog when it is flushed, so Suspend() works as expected with it). - @sa Resume(), wxLogNull + @see Resume(), wxLogNull */ static void Suspend(); }; @@ -780,13 +759,12 @@ public: it simply prints the message to the standard output using the title as prefix. @param title - The title of the message box shown to the user or the prefix - of the message string - + The title of the message box shown to the user or the prefix + of the message string @param text - The text to show to the user + The text to show to the user - @sa wxLogFatalError + @see wxLogFatalError */ void wxSafeShowMessage(const wxString& title, const wxString& text); diff --git a/interface/longlong.h b/interface/longlong.h index 4202cf5314..e8b815fe64 100644 --- a/interface/longlong.h +++ b/interface/longlong.h @@ -133,10 +133,9 @@ public: /** Assignment operator from unsigned long long. The sign bit will be copied too. - This function is new since wxWidgets version 2.7.0 */ - wxLongLong& operator operator=(const wxULongLong & ll); + wxLongLong& operator operator=(const wxULongLong& ll); }; @@ -148,6 +147,7 @@ public: This macro is defined to contain the @c printf() format specifier using which 64 bit integer numbers (i.e. those of type @c wxLongLong_t) can be printed. Example of using it: + @code #ifdef wxLongLong_t wxLongLong_t ll = wxLL(0x1234567890abcdef); @@ -155,33 +155,35 @@ public: #endif @endcode - @sa wxLL + @see wxLL */ /** This macro is defined for the platforms with a native 64 bit integer type and allows to define unsigned 64 bit compile time constants: + @code #ifdef wxLongLong_t unsigned wxLongLong_t ll = wxULL(0x1234567890abcdef); #endif @endcode - @sa wxLL, wxLongLong + @see wxLL, wxLongLong */ -#define wxLongLong_t wxULL(number) /* implementation is private */ +wxLongLong_t wxULL(number); /** This macro is defined for the platforms with a native 64 bit integer type and allows to define 64 bit compile time constants: + @code #ifdef wxLongLong_t wxLongLong_t ll = wxLL(0x1234567890abcdef); #endif @endcode - @sa wxULL, wxLongLong + @see wxULL, wxLongLong */ -#define wxLongLong_t wxLL(number) /* implementation is private */ +wxLongLong_t wxLL(number); diff --git a/interface/math.h b/interface/math.h index e122fa02bf..8e9d46ac17 100644 --- a/interface/math.h +++ b/interface/math.h @@ -7,7 +7,7 @@ ///////////////////////////////////////////////////////////////////////////// /** -Returns a non-zero value if @e x is neither infinite nor NaN (not a number), +Returns a non-zero value if @a x is neither infinite nor NaN (not a number), returns 0 otherwise. */ int wxFinite(double x); diff --git a/interface/mdi.h b/interface/mdi.h index 7444b51a85..582641d692 100644 --- a/interface/mdi.h +++ b/interface/mdi.h @@ -27,15 +27,14 @@ public: Constructor, creating the window. @param parent - The window parent. - + The window parent. @param style - The window style. Currently unused. + The window style. Currently unused. @remarks The second style of constructor is called within - wxMDIParentFrame::OnCreateClient. + wxMDIParentFrame::OnCreateClient. - @sa wxMDIParentFrame::wxMDIParentFrame, wxMDIParentFrame::OnCreateClient + @see wxMDIParentFrame::wxMDIParentFrame, wxMDIParentFrame::OnCreateClient */ wxMDIClientWindow(); wxMDIClientWindow(wxMDIParentFrame* parent, long style = 0); @@ -113,44 +112,40 @@ public: Constructor, creating the window. @param parent - The window parent. This should be @NULL. - + The window parent. This should be @NULL. @param id - The window identifier. It may take a value of -1 to indicate a default value. - + The window identifier. It may take a value of -1 to indicate a default + value. @param title - The caption to be displayed on the frame's title bar. - + The caption to be displayed on the frame's title bar. @param pos - The window position. The value wxDefaultPosition indicates a default position, chosen by - either the windowing system or wxWidgets, depending on platform. - + The window position. The value wxDefaultPosition indicates a default position, + chosen by + either the windowing system or wxWidgets, depending on platform. @param size - The window size. The value wxDefaultSize indicates a default size, chosen by - either the windowing system or wxWidgets, depending on platform. - + The window size. The value wxDefaultSize indicates a default size, chosen by + either the windowing system or wxWidgets, depending on platform. @param style - The window style. See wxMDIParentFrame. - + The window style. See wxMDIParentFrame. @param name - The name of the window. This parameter is used to associate a name with the + The name of the window. This parameter is used to associate a name with the item, - allowing the application user to set Motif resource values for - individual windows. + allowing the application user to set Motif resource values for + individual windows. @remarks During the construction of the frame, the client window will be - created. To use a different class from - wxMDIClientWindow, override - OnCreateClient(). + created. To use a different class from + wxMDIClientWindow, override + OnCreateClient(). - @sa Create(), OnCreateClient() + @see Create(), OnCreateClient() */ wxMDIParentFrame(); wxMDIParentFrame(wxWindow* parent, wxWindowID id, const wxString& title, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, - long style = wxDEFAULT_FRAME_STYLE | wxVSCROLL | wxHSCROLL, + long style = wxDEFAULT_FRAME_STYLE | wxVSCROLL | wxHSCROLL, const wxString& name = "frame"); //@} @@ -162,28 +157,28 @@ public: /** Activates the MDI child following the currently active one. - @sa ActivatePrevious() + @see ActivatePrevious() */ void ActivateNext(); /** Activates the MDI child preceding the currently active one. - @sa ActivateNext() + @see ActivateNext() */ void ActivatePrevious(); /** Arranges any iconized (minimized) MDI child windows. - @sa Cascade(), Tile() + @see Cascade(), Tile() */ void ArrangeIcons(); /** Arranges the MDI child windows in a cascade. - @sa Tile(), ArrangeIcons() + @see Tile(), ArrangeIcons() */ void Cascade(); @@ -195,7 +190,7 @@ public: const wxString& title, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, - long style = wxDEFAULT_FRAME_STYLE | wxVSCROLL | wxHSCROLL, + long style = wxDEFAULT_FRAME_STYLE | wxVSCROLL | wxHSCROLL, const wxString& name = "frame"); /** @@ -207,31 +202,30 @@ public: This gets the size of the frame 'client area' in pixels. @param width - Receives the client width in pixels. - + Receives the client width in pixels. @param height - Receives the client height in pixels. + Receives the client height in pixels. @remarks The client area is the area which may be drawn on by the - programmer, excluding title bar, border, status bar, - and toolbar if present. + programmer, excluding title bar, border, status bar, + and toolbar if present. - @sa GetToolBar(), SetToolBar(), - wxMDIClientWindow + @see GetToolBar(), SetToolBar(), + wxMDIClientWindow */ virtual void GetClientSize(int* width, int* height); /** Returns a pointer to the client window. - @sa OnCreateClient() + @see OnCreateClient() */ wxMDIClientWindow* GetClientWindow(); /** Returns the window being used as the toolbar for this frame. - @sa SetToolBar() + @see SetToolBar() */ virtual wxWindow* GetToolBar(); @@ -251,10 +245,10 @@ public: example: @remarks You might wish to derive from wxMDIClientWindow in order to - implement different erase behaviour, for example, - such as painting a bitmap on the background. + implement different erase behaviour, for example, such + as painting a bitmap on the background. - @sa GetClientWindow(), wxMDIClientWindow + @see GetClientWindow(), wxMDIClientWindow */ virtual wxMDIClientWindow* OnCreateClient(); @@ -264,13 +258,13 @@ public: of the toolbar MDI client window. @param toolbar - Toolbar to manage. + Toolbar to manage. @remarks When the frame is resized, the toolbar is resized to be the - width of the frame client area, and the toolbar - height is kept the same. + width of the frame client area, and the toolbar height + is kept the same. - @sa GetToolBar(), GetClientSize() + @see GetToolBar(), GetClientSize() */ virtual void SetToolBar(wxWindow* toolbar); @@ -278,17 +272,14 @@ public: Call this to change the current Window menu. Ownership of the menu object passes to the frame when you call this function. - This call is available under Windows only. - To remove the window completely, use the wxFRAME_NO_WINDOW_MENU window style. */ void SetWindowMenu(wxMenu* menu); /** Tiles the MDI child windows either horizontally or vertically depending on - whether @e orient is wxHORIZONTAL or wxVERTICAL. - + whether @a orient is wxHORIZONTAL or wxVERTICAL. Currently only implemented for MSW, does nothing under the other platforms. */ void Tile(wxOrientation orient = wxHORIZONTAL); @@ -343,34 +334,30 @@ public: Constructor, creating the window. @param parent - The window parent. This should not be @NULL. - + The window parent. This should not be @NULL. @param id - The window identifier. It may take a value of -1 to indicate a default value. - + The window identifier. It may take a value of -1 to indicate a default + value. @param title - The caption to be displayed on the frame's title bar. - + The caption to be displayed on the frame's title bar. @param pos - The window position. The value wxDefaultPosition indicates a default position, chosen by - either the windowing system or wxWidgets, depending on platform. - + The window position. The value wxDefaultPosition indicates a default position, + chosen by + either the windowing system or wxWidgets, depending on platform. @param size - The window size. The value wxDefaultSize indicates a default size, chosen by - either the windowing system or wxWidgets, depending on platform. - + The window size. The value wxDefaultSize indicates a default size, chosen by + either the windowing system or wxWidgets, depending on platform. @param style - The window style. See wxMDIChildFrame. - + The window style. See wxMDIChildFrame. @param name - The name of the window. This parameter is used to associate a name with the + The name of the window. This parameter is used to associate a name with the item, - allowing the application user to set Motif resource values for - individual windows. + allowing the application user to set Motif resource values for + individual windows. @remarks None. - @sa Create() + @see Create() */ wxMDIChildFrame(); wxMDIChildFrame(wxMDIParentFrame* parent, wxWindowID id, @@ -389,7 +376,7 @@ public: /** Activates this MDI child frame. - @sa Maximize(), Restore() + @see Maximize(), Restore() */ void Activate(); @@ -407,7 +394,7 @@ public: /** Maximizes this MDI child frame. - @sa Activate(), Restore() + @see Activate(), Restore() */ void Maximize(bool maximize); diff --git a/interface/mediactrl.h b/interface/mediactrl.h index 7ce2ec12e6..4fc5ee892f 100644 --- a/interface/mediactrl.h +++ b/interface/mediactrl.h @@ -59,32 +59,24 @@ public: to see if wxMediaCtrl is available on the system. parent - parent of this control. Must not be @NULL. - + parent of this control. Must not be @NULL. @param id - id to use for events - + id to use for events @param fileName - If not empty, the path of a file to open. - + If not empty, the path of a file to open. @param pos - Position to put control at. - + Position to put control at. @param size - Size to put the control at and to stretch movie to. - + Size to put the control at and to stretch movie to. @param style - Optional styles. - + Optional styles. @param szBackend - Name of backend you want to use, leave blank to make - wxMediaCtrl figure it out. - + Name of backend you want to use, leave blank to make + wxMediaCtrl figure it out. @param validator - validator to use. - + validator to use. @param name - Window name. + Window name. */ wxMediaCtrl(); wxMediaCtrl(wxWindow* parent, wxWindowID id); @@ -97,13 +89,11 @@ public: to do to choose a specific backend is to pass the name of the backend class to Create(). - The following are valid backend identifiers - @b wxMEDIABACKEND_DIRECTSHOW - Use ActiveMovie/DirectShow. Uses the native ActiveMovie (I.E. DirectShow) control. Default backend on Windows and supported by nearly all Windows versions, even some @@ -112,14 +102,11 @@ public: @b wxMEDIABACKEND_QUICKTIME - Use QuickTime. Mac Only. WARNING: May not working correctly embedded in a wxNotebook. - @b wxMEDIABACKEND_GSTREAMER - Use GStreamer. Unix Only. Requires GStreamer 0.8 along with at the very least the xvimagesink, xoverlay, and gst-play modules of gstreamer to function. You need the correct @@ -128,7 +115,6 @@ public: @b wxMEDIABACKEND_WMP10 - Uses Windows Media Player 10 (Windows only) - works on mobile machines with Windows Media Player 10 and desktop machines with either Windows Media Player 9 or 10 @@ -157,32 +143,24 @@ public: use, wxMediaCtrl tries each of its backends until one that can render the path referred to by fileName can be found. parent - parent of this control. Must not be @NULL. - + parent of this control. Must not be @NULL. @param id - id to use for events - + id to use for events @param fileName - If not empty, the path of a file to open. - + If not empty, the path of a file to open. @param pos - Position to put control at. - + Position to put control at. @param size - Size to put the control at and to stretch movie to. - + Size to put the control at and to stretch movie to. @param style - Optional styles. - + Optional styles. @param szBackend - Name of backend you want to use, leave blank to make - wxMediaCtrl figure it out. - + Name of backend you want to use, leave blank to make + wxMediaCtrl figure it out. @param validator - validator to use. - + validator to use. @param name - Window name. + Window name. */ bool Create(wxWindow* parent, wxWindowID id); @@ -192,13 +170,10 @@ public: in wxMediaBackend correspond to those in wxMediaCtrl except for CreateControl which does the actual creation of the control, in cases where a custom control is not needed you may simply call wxControl::Create. - You need to make sure to use the DECLARE_CLASS and IMPLEMENT_CLASS macros. - The only real tricky part is that you need to make sure the file in compiled in, which if there are just backends in there will not happen and you may need to use a force link hack (see http://www.wxwidgets.org/wiki/index.php/RTTI). - This is a rather simple example of how to create a backend in the wxActiveXContainer documentation. */ @@ -222,20 +197,16 @@ public: /** Obtains the state the playback of the media is in - - @b wxMEDIASTATE_STOPPED - The movie has stopped. @b wxMEDIASTATE_PAUSED - The movie is paused. @b wxMEDIASTATE_PLAYING - The movie is currently playing. */ wxMediaCtrlState GetState(); @@ -274,7 +245,6 @@ public: event to its parent window, at which point the event handler can choose to veto the event, preventing the stream from actually stopping. - Example: When wxMediaCtrl stops, either by the EVT_MEDIA_STOP not being @@ -286,7 +256,6 @@ public: because some streams are not seekable, and when stop is called on them they return to the beginning, thus wxMediaCtrl tries to keep consistant for all types of media. - Note that when changing the state of the media through Play() and other methods, the media may not actually be in the wxMEDIASTATE_PLAYING, for example. If you are relying on the @@ -329,13 +298,11 @@ public: since it relies on native system calls that may not technically have mp3 decoding available, for example, it falls outside the realm of licensing restrictions). - For general operation, all you need to do is call Load() to load the file you want to render, catch the EVT_MEDIA_LOADED event, and then call Play() to show the video/audio of the media in that event. - More complex operations are generally more heavily dependant on the capabilities of the backend. For example, QuickTime cannot set the playback rate of certain streaming media - while DirectShow is @@ -375,25 +342,20 @@ public: default controls provided by the toolkit. The function takes a @c wxMediaCtrlPlayerControls enumeration as follows: - @b wxMEDIACTRLPLAYERCONTROLS_NONE - No controls. return wxMediaCtrl to it's default state. @b wxMEDIACTRLPLAYERCONTROLS_STEP - Step controls like fastfoward, step one frame etc. @b wxMEDIACTRLPLAYERCONTROLS_VOLUME - Volume controls like the speaker icon, volume slider, etc. @b wxMEDIACTRLPLAYERCONTROLS_DEFAULT - Default controls for the toolkit. Currently a typedef for wxMEDIACTRLPLAYERCONTROLS_STEP and wxMEDIACTRLPLAYERCONTROLS_VOLUME. @@ -406,7 +368,6 @@ public: /** Stops the media. - See Operation for an overview of how stopping works. */ @@ -429,7 +390,6 @@ public: In addition, the backend may modify GetBestSize() to include the size of the extra controls - so if you want the real size of the video just disable ShowPlayerControls(). - The idea with setting GetBestSize to the size of the video is that GetBestSize is a wxWindow-derived function that is called when sizers on a window recalculate. What this means is that diff --git a/interface/memory.h b/interface/memory.h index 5a15441168..aa3b52849a 100644 --- a/interface/memory.h +++ b/interface/memory.h @@ -56,8 +56,8 @@ public: checkpoint. @returns Returns the number of errors, so a value of zero represents - success. Returns -1 if an error was detected that - prevents further checking. + success. Returns -1 if an error was detected that + prevents further checking. */ int Check(); @@ -75,7 +75,7 @@ public: errors. By default, this is @false since it slows down execution considerably. - @sa SetCheckPrevious() + @see SetCheckPrevious() */ bool GetCheckPrevious(); @@ -85,7 +85,7 @@ public: operators store or use information about memory allocation. Otherwise, a straight malloc and free will be performed by these operators. - @sa SetDebugMode() + @see SetDebugMode() */ bool GetDebugMode(); @@ -96,19 +96,17 @@ public: a different level will only have an effect if trace statements in the application specify a value other than one. - This is obsolete, replaced by wxLog functionality. - @sa SetLevel() + @see SetLevel() */ int GetLevel(); /** Returns the output stream associated with the debug context. - This is obsolete, replaced by wxLog functionality. - @sa SetStream() + @see SetStream() */ ostream GetStream(); @@ -116,7 +114,6 @@ public: Returns a pointer to the output stream buffer associated with the debug context. There may not necessarily be a stream buffer if the stream has been set by the user. - This is obsolete, replaced by wxLog functionality. */ streambuf* GetStreamBuf(); @@ -124,10 +121,9 @@ public: /** Returns @true if there is a stream currently associated with the debug context. - This is obsolete, replaced by wxLog functionality. - @sa SetStream(), GetStream() + @see SetStream(), GetStream() */ bool HasStream(); @@ -135,7 +131,7 @@ public: Prints a list of the classes declared in this application, giving derivation and whether instances of this class can be dynamically created. - @sa PrintStatistics() + @see PrintStatistics() */ bool PrintClasses(); @@ -145,19 +141,19 @@ public: allocations is printed, together with the total size. @param detailed - If @true, the function will also print how many - objects of each class have been allocated, and the space taken by - these class instances. + If @true, the function will also print how many + objects of each class have been allocated, and the space taken by + these class instances. - @sa PrintStatistics() + @see PrintStatistics() */ - bool PrintStatistics(bool detailed = @true); + bool PrintStatistics(bool detailed = true); /** Tells the memory allocator to check all previous memory blocks for errors. By default, this is @false since it slows down execution considerably. - @sa GetCheckPrevious() + @see GetCheckPrevious() */ void SetCheckPrevious(bool check); @@ -167,23 +163,22 @@ public: that have been performed up to this point. @param all - If @true, the checkpoint is reset to include all - memory allocations since the program started. + If @true, the checkpoint is reset to include all + memory allocations since the program started. */ - void SetCheckpoint(bool all = @false); + void SetCheckpoint(bool all = false); /** Sets the debug mode on or off. If debug mode is on, the wxObject new and delete operators store or use information about memory allocation. Otherwise, a straight malloc and free will be performed by these operators. - By default, debug mode is on if __WXDEBUG__ is defined. If the application uses this function, it should make sure that all object memory allocated is deallocated with the same value of debug mode. Otherwise, the delete operator might try to look for memory information that does not exist. - @sa GetDebugMode() + @see GetDebugMode() */ void SetDebugMode(bool debug); @@ -201,10 +196,9 @@ public: a different level will only have an effect if trace statements in the application specify a value other than one. - This is obsolete, replaced by wxLog functionality. - @sa GetLevel() + @see GetLevel() */ void SetLevel(int level); @@ -213,7 +207,6 @@ public: called after all files with global instances of wxDebugContextDumpDelayCounter have run their destructors. - The shutdown function must be take no parameters and return nothing. */ void SetShutdownNotifyFunction(wxShutdownNotifyFunction func); @@ -222,7 +215,6 @@ public: Sets the debugging stream to be the debugger (Windows) or standard error (other platforms). This is the default setting. The existing stream will be flushed and deleted. - This is obsolete, replaced by wxLog functionality. */ bool SetStandardError(); @@ -231,16 +223,14 @@ public: Sets the stream and optionally, stream buffer associated with the debug context. This operation flushes and deletes the existing stream (and stream buffer if any). - This is obsolete, replaced by wxLog functionality. @param stream - Stream to associate with the debug context. Do not set this to @NULL. - + Stream to associate with the debug context. Do not set this to @NULL. @param streamBuf - Stream buffer to associate with the debug context. + Stream buffer to associate with the debug context. */ - void SetStream(ostream* stream, streambuf* streamBuf = @NULL); + void SetStream(ostream* stream, streambuf* streamBuf = NULL); }; @@ -251,7 +241,6 @@ public: /** @b NB: This function is now obsolete, replaced by @ref overview_logfunctions "Log functions". - Calls wxTraceLevel with printf-style variable argument syntax. Output is directed to the current output stream (see wxDebugContext). The first argument should be the level at which this information is appropriate. @@ -264,7 +253,6 @@ public: /** @b NB: This function is now obsolete, replaced by @ref overview_logfunctions "Log functions". - Takes printf-style variable argument syntax. Output is directed to the current output stream (see wxDebugContext). */ @@ -273,7 +261,6 @@ void wxTrace(const wxString& fmt, ... ); /** @b NB: This macro is now obsolete, replaced by @ref overview_logfunctions "Log functions". - Calls wxTrace with printf-style variable argument syntax. Output is directed to the current output stream (see wxDebugContext). */ diff --git a/interface/menu.h b/interface/menu.h index 537679b5ec..9f1709e8bb 100644 --- a/interface/menu.h +++ b/interface/menu.h @@ -16,7 +16,7 @@ @category{menus} @seealso - wxMenu, @ref overview_eventhandlingoverview "Event handling overview" + wxMenu, @ref overview_eventhandlingoverview */ class wxMenuBar : public wxWindow { @@ -26,17 +26,15 @@ public: Construct a menu bar from arrays of menus and titles. @param n - The number of menus. - + The number of menus. @param menus - An array of menus. Do not use this array again - it now belongs to the - menu bar. - + An array of menus. Do not use this array again - it now belongs to the + menu bar. @param titles - An array of title strings. Deallocate this array after creating the menu bar. - + An array of title strings. Deallocate this array after creating the menu + bar. @param style - If wxMB_DOCKABLE the menu bar can be detached (wxGTK only). + If wxMB_DOCKABLE the menu bar can be detached (wxGTK only). */ wxMenuBar(long style = 0); wxMenuBar(size_t n, wxMenu* menus[], const wxString titles[], @@ -53,28 +51,26 @@ public: Adds the item to the end of the menu bar. @param menu - The menu to add. Do not deallocate this menu after calling Append. - + The menu to add. Do not deallocate this menu after calling Append. @param title - The title of the menu. + The title of the menu. @returns @true on success, @false if an error occurred. - @sa Insert() + @see Insert() */ - bool Append(wxMenu * menu, const wxString& title); + bool Append(wxMenu* menu, const wxString& title); /** Checks or unchecks a menu item. @param id - The menu item identifier. - + The menu item identifier. @param check - If @true, checks the menu item, otherwise the item is unchecked. + If @true, checks the menu item, otherwise the item is unchecked. @remarks Only use this when the menu bar has been associated with a - frame; otherwise, use the wxMenu equivalent call. + frame; otherwise, use the wxMenu equivalent call. */ void Check(int id, const bool check); @@ -82,13 +78,12 @@ public: Enables or disables (greys out) a menu item. @param id - The menu item identifier. - + The menu item identifier. @param enable - @true to enable the item, @false to disable it. + @true to enable the item, @false to disable it. @remarks Only use this when the menu bar has been associated with a - frame; otherwise, use the wxMenu equivalent call. + frame; otherwise, use the wxMenu equivalent call. */ void Enable(int id, const bool enable); @@ -96,10 +91,9 @@ public: Enables or disables a whole menu. @param pos - The position of the menu, starting from zero. - + The position of the menu, starting from zero. @param enable - @true to enable the menu, @false to disable it. + @true to enable the menu, @false to disable it. @remarks Only use this when the menu bar has been associated with a frame. */ @@ -109,18 +103,17 @@ public: Finds the menu item object associated with the given menu item identifier. @param id - Menu item identifier. - + Menu item identifier. @param menu - If not @NULL, menu will get set to the associated menu. + If not @NULL, menu will get set to the associated menu. @returns The found menu item object, or @NULL if one was not found. */ - wxMenuItem * FindItem(int id, wxMenu menu = @NULL); + wxMenuItem* FindItem(int id, wxMenu menu = NULL); /** - Returns the index of the menu with the given @e title or @c wxNOT_FOUND if no - such menu exists in this menubar. The @e title parameter may specify either + Returns the index of the menu with the given @a title or @c wxNOT_FOUND if no + such menu exists in this menubar. The @a title parameter may specify either the menu title (with accelerator characters, i.e. @c "File") or just the menu label (@c "File") indifferently. */ @@ -130,15 +123,14 @@ public: Finds the menu item id for a menu name/menu item string pair. @param menuString - Menu title to find. - + Menu title to find. @param itemString - Item to find. + Item to find. @returns The menu item identifier, or wxNOT_FOUND if none was found. @remarks Any special menu codes are stripped out of source and target - strings before matching. + strings before matching. */ int FindMenuItem(const wxString& menuString, const wxString& itemString); @@ -147,12 +139,12 @@ public: Gets the help string associated with the menu item identifier. @param id - The menu item identifier. + The menu item identifier. @returns The help string, or the empty string if there was no help string - or the menu item was not found. + or the menu item was not found. - @sa SetHelpString() + @see SetHelpString() */ wxString GetHelpString(int id); @@ -160,10 +152,10 @@ public: Gets the label associated with a menu item. @param id - The menu item identifier. + The menu item identifier. @returns The menu item label, or the empty string if the item was not - found. + found. @remarks Use only after the menubar has been associated with a frame. */ @@ -175,18 +167,18 @@ public: title string during its construction. @param pos - Position of the menu on the menu bar, starting from zero. + Position of the menu on the menu bar, starting from zero. @returns The menu label, or the empty string if the menu was not found. @remarks Use only after the menubar has been associated with a frame. - @sa SetLabelTop() + @see SetLabelTop() */ wxString GetLabelTop(int pos); /** - Returns the menu at @e menuIndex (zero-based). + Returns the menu at @a menuIndex (zero-based). */ wxMenu* GetMenu(int menuIndex); @@ -201,13 +193,13 @@ public: title string during its construction. @param pos - Position of the menu on the menu bar, starting from zero. + Position of the menu on the menu bar, starting from zero. @returns The menu label, or the empty string if the menu was not found. @remarks Use only after the menubar has been associated with a frame. - @sa GetMenuLabelText(), SetMenuLabel() + @see GetMenuLabelText(), SetMenuLabel() */ wxString GetMenuLabel(int pos); @@ -217,13 +209,13 @@ public: title string during its construction. @param pos - Position of the menu on the menu bar, starting from zero. + Position of the menu on the menu bar, starting from zero. @returns The menu label, or the empty string if the menu was not found. @remarks Use only after the menubar has been associated with a frame. - @sa GetMenuLabel(), SetMenuLabel() + @see GetMenuLabel(), SetMenuLabel() */ wxString GetMenuLabelText(int pos); @@ -234,25 +226,23 @@ public: Append(). @param pos - The position of the new menu in the menu bar - + The position of the new menu in the menu bar @param menu - The menu to add. wxMenuBar owns the menu and will free it. - + The menu to add. wxMenuBar owns the menu and will free it. @param title - The title of the menu. + The title of the menu. @returns @true on success, @false if an error occurred. - @sa Append() + @see Append() */ - bool Insert(size_t pos, wxMenu * menu, const wxString& title); + bool Insert(size_t pos, wxMenu* menu, const wxString& title); /** Determines whether an item is checked. @param id - The menu item identifier. + The menu item identifier. @returns @true if the item was found and is checked, @false otherwise. */ @@ -262,7 +252,7 @@ public: Determines whether an item is enabled. @param id - The menu item identifier. + The menu item identifier. @returns @true if the item was found and is enabled, @false otherwise. */ @@ -279,40 +269,36 @@ public: Insert() to change the menubar dynamically. - @sa Replace() + @see Replace() */ - wxMenu * Remove(size_t pos); + wxMenu* Remove(size_t pos); /** Replaces the menu at the given position with another one. @param pos - The position of the new menu in the menu bar - + The position of the new menu in the menu bar @param menu - The menu to add. - + The menu to add. @param title - The title of the menu. + The title of the menu. @returns The menu which was previously at position pos. The caller is - responsible for deleting it. + responsible for deleting it. - @sa Insert(), Remove() + @see Insert(), Remove() */ - wxMenu * Replace(size_t pos, wxMenu * menu, - const wxString& title); + wxMenu* Replace(size_t pos, wxMenu* menu, const wxString& title); /** Sets the help string associated with a menu item. @param id - Menu item identifier. - + Menu item identifier. @param helpString - Help string to associate with the menu item. + Help string to associate with the menu item. - @sa GetHelpString() + @see GetHelpString() */ void SetHelpString(int id, const wxString& helpString); @@ -320,14 +306,13 @@ public: Sets the label of a menu item. @param id - Menu item identifier. - + Menu item identifier. @param label - Menu item label. + Menu item label. @remarks Use only after the menubar has been associated with a frame. - @sa GetLabel() + @see GetLabel() */ void SetLabel(int id, const wxString& label); @@ -335,14 +320,13 @@ public: Sets the label of a top-level menu. @param pos - The position of a menu on the menu bar, starting from zero. - + The position of a menu on the menu bar, starting from zero. @param label - The menu label. + The menu label. @remarks Use only after the menubar has been associated with a frame. - @sa GetLabelTop() + @see GetLabelTop() */ void SetLabelTop(int pos, const wxString& label); @@ -350,10 +334,9 @@ public: Sets the label of a top-level menu. @param pos - The position of a menu on the menu bar, starting from zero. - + The position of a menu on the menu bar, starting from zero. @param label - The menu label. + The menu label. @remarks Use only after the menubar has been associated with a frame. */ @@ -403,8 +386,8 @@ public: @category{menus} @seealso - wxMenuBar, wxWindow::PopupMenu, @ref overview_eventhandlingoverview "Event - handling overview", @ref overview_wxfilehistory "wxFileHistory (most recently used files menu)" + wxMenuBar, wxWindow::PopupMenu, @ref overview_eventhandlingoverview, @ref + overview_wxfilehistory "wxFileHistory (most recently used files menu)" */ class wxMenu : public wxEvtHandler { @@ -414,7 +397,7 @@ public: Constructs a wxMenu object. @param style - If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only). + If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only). */ wxMenu(const wxString& title = "", long style = 0); wxMenu(long style); @@ -422,7 +405,6 @@ public: /** Destructor, destroying the menu. - Note: under Motif, a popup menu must have a valid parent (the window it was last popped up on) when being destroyed. Therefore, make sure you delete or re-use the popup menu @e before destroying the @@ -440,39 +422,34 @@ public: such as bitmaps and fonts. @param id - The menu command identifier. - + The menu command identifier. @param item - The string to appear on the menu item. - + The string to appear on the menu item. @param menu - Pull-right submenu. - + Pull-right submenu. @param kind - May be wxITEM_SEPARATOR, wxITEM_NORMAL, - wxITEM_CHECK or wxITEM_RADIO - + May be wxITEM_SEPARATOR, wxITEM_NORMAL, + wxITEM_CHECK or wxITEM_RADIO @param helpString - An optional help string associated with the item. - By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays - this string in the status line. - + An optional help string associated with the item. + By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays + this string in the status line. @param menuItem - A menuitem object. It will be owned by the wxMenu object after this function - is called, so do not delete it yourself. + A menuitem object. It will be owned by the wxMenu object after this function + is called, so do not delete it yourself. @remarks This command can be used after the menu has been shown, as well - as on initial creation of a menu or menubar. + as on initial creation of a menu or menubar. - @sa AppendSeparator(), AppendCheckItem(), AppendRadioItem(), - AppendSubMenu(), Insert(), SetLabel(), - GetHelpString(), SetHelpString(), wxMenuItem + @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(), + AppendSubMenu(), Insert(), SetLabel(), + GetHelpString(), SetHelpString(), wxMenuItem */ wxMenuItem* Append(int id, const wxString& item = "", const wxString& helpString = "", wxItemKind kind = wxITEM_NORMAL); wxMenuItem* Append(int id, const wxString& item, - wxMenu * subMenu, + wxMenu* subMenu, const wxString& helpString = ""); wxMenuItem* Append(wxMenuItem* menuItem); //@} @@ -480,7 +457,7 @@ public: /** Adds a checkable item to the end of the menu. - @sa Append(), InsertCheckItem() + @see Append(), InsertCheckItem() */ wxMenuItem* AppendCheckItem(int id, const wxString& item, const wxString& helpString = ""); @@ -490,7 +467,7 @@ public: group and when an item in the group is checked, all the others are automatically unchecked. - @sa Append(), InsertRadioItem() + @see Append(), InsertRadioItem() */ wxMenuItem* AppendRadioItem(int id, const wxString& item, const wxString& helpString = ""); @@ -498,18 +475,17 @@ public: /** Adds a separator to the end of the menu. - @sa Append(), InsertSeparator() + @see Append(), InsertSeparator() */ wxMenuItem* AppendSeparator(); /** - Adds the given @e submenu to this menu. @e text is the text shown in the - menu for it and @e help is the help string shown in the status bar when the + Adds the given @a submenu to this menu. @a text is the text shown in the + menu for it and @a help is the help string shown in the status bar when the submenu item is selected. */ - wxMenuItem * AppendSubMenu(wxMenu * submenu, - const wxString& text, - const wxString& help = wxEmptyString); + wxMenuItem* AppendSubMenu(wxMenu* submenu, const wxString& text, + const wxString& help = wxEmptyString); /** Inserts a break in a menu, causing the next appended item to appear in a new @@ -521,12 +497,11 @@ public: Checks or unchecks the menu item. @param id - The menu item identifier. - + The menu item identifier. @param check - If @true, the item will be checked, otherwise it will be unchecked. + If @true, the item will be checked, otherwise it will be unchecked. - @sa IsChecked() + @see IsChecked() */ void Check(int id, const bool check); @@ -537,15 +512,14 @@ public: delete a submenu. @param id - Id of the menu item to be deleted. - + Id of the menu item to be deleted. @param item - Menu item to be deleted. + Menu item to be deleted. - @sa FindItem(), Destroy(), Remove() + @see FindItem(), Destroy(), Remove() */ void Delete(int id); - void Delete(wxMenuItem * item); + void Delete(wxMenuItem* item); //@} //@{ @@ -555,27 +529,25 @@ public: (for example, to reuse it later). @param id - Id of the menu item to be deleted. - + Id of the menu item to be deleted. @param item - Menu item to be deleted. + Menu item to be deleted. - @sa FindItem(), Deletes(), Remove() + @see FindItem(), Deletes(), Remove() */ void Destroy(int id); - void Destroy(wxMenuItem * item); + void Destroy(wxMenuItem* item); //@} /** Enables or disables (greys out) a menu item. @param id - The menu item identifier. - + The menu item identifier. @param enable - @true to enable the menu item, @false to disable it. + @true to enable the menu item, @false to disable it. - @sa IsEnabled() + @see IsEnabled() */ void Enable(int id, const bool enable); @@ -585,23 +557,21 @@ public: optionally, the (sub)menu it belongs to. @param itemString - Menu item string to find. - + Menu item string to find. @param id - Menu item identifier. - + Menu item identifier. @param menu - If the pointer is not @NULL, it will be filled with the item's - parent menu (if the item was found) + If the pointer is not @NULL, it will be filled with the item's + parent menu (if the item was found) @returns First form: menu item identifier, or wxNOT_FOUND if none is - found. + found. @remarks Any special menu codes are stripped out of source and target - strings before matching. + strings before matching. */ int FindItem(const wxString& itemString); - wxMenuItem * FindItem(int id, wxMenu ** menu = @NULL); + wxMenuItem* FindItem(int id, wxMenu** menu = NULL); //@} /** @@ -613,12 +583,12 @@ public: Returns the help string associated with a menu item. @param id - The menu item identifier. + The menu item identifier. @returns The help string, or the empty string if there is no help string - or the item was not found. + or the item was not found. - @sa SetHelpString(), Append() + @see SetHelpString(), Append() */ wxString GetHelpString(int id); @@ -626,11 +596,11 @@ public: Returns a menu item label. @param id - The menu item identifier. + The menu item identifier. @returns The item label, or the empty string if the item was not found. - @sa GetLabelText(), SetLabel() + @see GetLabelText(), SetLabel() */ wxString GetLabel(int id); @@ -639,11 +609,11 @@ public: accelerators. @param id - The menu item identifier. + The menu item identifier. @returns The item label, or the empty string if the item was not found. - @sa GetLabel(), SetLabel() + @see GetLabel(), SetLabel() */ wxString GetLabelText(int id); @@ -662,21 +632,21 @@ public: Returns the title of the menu. @remarks This is relevant only to popup menus, use - wxMenuBar::GetMenuLabel for the menus in the menubar. + wxMenuBar::GetMenuLabel for the menus in the menubar. - @sa SetTitle() + @see SetTitle() */ wxString GetTitle(); //@{ /** - Inserts the given @e item before the position @e pos. Inserting the item + Inserts the given @a item before the position @e pos. Inserting the item at position GetMenuItemCount() is the same as appending it. - @sa Append(), Prepend() + @see Append(), Prepend() */ - wxMenuItem* Insert(size_t pos, wxMenuItem * item); + wxMenuItem* Insert(size_t pos, wxMenuItem* item); wxMenuItem* Insert(size_t pos, int id, const wxString& item = "", const wxString& helpString = "", @@ -686,7 +656,7 @@ public: /** Inserts a checkable item at the given position. - @sa Insert(), AppendCheckItem() + @see Insert(), AppendCheckItem() */ wxMenuItem* InsertCheckItem(size_t pos, int id, const wxString& item, @@ -695,7 +665,7 @@ public: /** Inserts a radio item at the given position. - @sa Insert(), AppendRadioItem() + @see Insert(), AppendRadioItem() */ wxMenuItem* InsertRadioItem(size_t pos, int id, const wxString& item, @@ -704,7 +674,7 @@ public: /** Inserts a separator at the given position. - @sa Insert(), AppendSeparator() + @see Insert(), AppendSeparator() */ wxMenuItem* InsertSeparator(size_t pos); @@ -712,11 +682,11 @@ public: Determines whether a menu item is checked. @param id - The menu item identifier. + The menu item identifier. @returns @true if the menu item is checked, @false otherwise. - @sa Check() + @see Check() */ bool IsChecked(int id); @@ -724,22 +694,22 @@ public: Determines whether a menu item is enabled. @param id - The menu item identifier. + The menu item identifier. @returns @true if the menu item is enabled, @false otherwise. - @sa Enable() + @see Enable() */ bool IsEnabled(int id); //@{ /** - Inserts the given @e item at position 0, i.e. before all the other + Inserts the given @a item at position 0, i.e. before all the other existing items. - @sa Append(), Insert() + @see Append(), Insert() */ - wxMenuItem* Prepend(wxMenuItem * item); + wxMenuItem* Prepend(wxMenuItem* item); wxMenuItem* Prepend(int id, const wxString& item = "", const wxString& helpString = "", wxItemKind kind = wxITEM_NORMAL); @@ -748,7 +718,7 @@ public: /** Inserts a checkable item at position 0. - @sa Prepend(), AppendCheckItem() + @see Prepend(), AppendCheckItem() */ wxMenuItem* PrependCheckItem(int id, const wxString& item, const wxString& helpString = ""); @@ -756,7 +726,7 @@ public: /** Inserts a radio item at position 0. - @sa Prepend(), AppendRadioItem() + @see Prepend(), AppendRadioItem() */ wxMenuItem* PrependRadioItem(int id, const wxString& item, const wxString& helpString = ""); @@ -764,7 +734,7 @@ public: /** Inserts a separator at position 0. - @sa Prepend(), AppendSeparator() + @see Prepend(), AppendSeparator() */ wxMenuItem* PrependSeparator(); @@ -775,27 +745,25 @@ public: (especially useful with submenus). @param id - The identifier of the menu item to remove. - + The identifier of the menu item to remove. @param item - The menu item to remove. + The menu item to remove. @returns The item which was detached from the menu. */ - wxMenuItem * Remove(int id); - wxMenuItem * Remove(wxMenuItem * item); + wxMenuItem* Remove(int id); + wxMenuItem* Remove(wxMenuItem* item); //@} /** Sets an item's help string. @param id - The menu item identifier. - + The menu item identifier. @param helpString - The help string to set. + The help string to set. - @sa GetHelpString() + @see GetHelpString() */ void SetHelpString(int id, const wxString& helpString); @@ -803,12 +771,11 @@ public: Sets the label of a menu item. @param id - The menu item identifier. - + The menu item identifier. @param label - The menu item label to set. + The menu item label to set. - @sa Append(), GetLabel() + @see Append(), GetLabel() */ void SetLabel(int id, const wxString& label); @@ -816,20 +783,20 @@ public: Sets the title of the menu. @param title - The title to set. + The title to set. @remarks This is relevant only to popup menus, use - wxMenuBar::SetLabelTop for the menus in the menubar. + wxMenuBar::SetLabelTop for the menus in the menubar. - @sa GetTitle() + @see GetTitle() */ void SetTitle(const wxString& title); /** - Sends events to @e source (or owning window if @NULL) to update the + Sends events to @a source (or owning window if @NULL) to update the menu UI. This is called just before the menu is popped up with wxWindow::PopupMenu, but the application may call it at other times if required. */ - void UpdateUI(wxEvtHandler* source = @NULL); + void UpdateUI(wxEvtHandler* source = NULL); }; diff --git a/interface/menuitem.h b/interface/menuitem.h index 9ed935874c..bf32f16dbe 100644 --- a/interface/menuitem.h +++ b/interface/menuitem.h @@ -28,51 +28,44 @@ class wxMenuItem : public wxObject public: /** Constructs a wxMenuItem object. - Menu items can be standard, or "stock menu items'', or custom. For the standard menu items (such as commands to open a file, exit the program and so on, see @ref overview_stockitems "stock items" for the full list) it is enough to - specify just the stock ID and leave @e text and @e helpString empty. In - fact, leaving at least @e text empty for the stock menu items is strongly + specify just the stock ID and leave @a text and @a helpString empty. In + fact, leaving at least @a text empty for the stock menu items is strongly recommended as they will have appearance and keyboard interface (including standard accelerators) familiar to the user. - - For the custom (non-stock) menu items, @e text must be specified and while - @e helpString may be left empty, it's recommended to pass the item + For the custom (non-stock) menu items, @a text must be specified and while + @a helpString may be left empty, it's recommended to pass the item description (which is automatically shown by the library in the status bar when the menu item is selected) in this parameter. - Finally note that you can e.g. use a stock menu label without using its stock help string: + that is, stock properties are set independently one from the other. @param parentMenu - Menu that the menu item belongs to. - + Menu that the menu item belongs to. @param id - Identifier for this menu item, or wxID_SEPARATOR to indicate a separator. - + Identifier for this menu item, or wxID_SEPARATOR to indicate a separator. @param text - Text for the menu item, as shown on the menu. An accelerator - key can be specified using the ampersand '' character. In order to embed an - ampersand character in the menu item text, the ampersand must be doubled. - + Text for the menu item, as shown on the menu. An accelerator + key can be specified using the ampersand '' character. In order to embed an + ampersand character in the menu item text, the ampersand must be doubled. @param helpString - Optional help string that will be shown on the status bar. - + Optional help string that will be shown on the status bar. @param kind - May be wxITEM_SEPARATOR, wxITEM_NORMAL, - wxITEM_CHECK or wxITEM_RADIO - + May be wxITEM_SEPARATOR, wxITEM_NORMAL, + wxITEM_CHECK or wxITEM_RADIO @param subMenu - If non-@NULL, indicates that the menu item is a submenu. + If non-@NULL, indicates that the menu item is a submenu. */ - wxMenuItem(wxMenu* parentMenu = @NULL, int id = wxID_SEPARATOR, + wxMenuItem(wxMenu* parentMenu = NULL, int id = wxID_SEPARATOR, const wxString& text = "", const wxString& helpString = "", wxItemKind kind = wxITEM_NORMAL, - wxMenu* subMenu = @NULL); + wxMenu* subMenu = NULL); /** Destructor. @@ -81,15 +74,14 @@ public: /** Checks or unchecks the menu item. - Note that this only works when the item is already appended to a menu. */ - void Check(bool check = @true); + void Check(bool check = true); /** Enables or disables the menu item. */ - void Enable(bool enable = @true); + void Enable(bool enable = true); /** Returns the background colour associated with the menu item (Windows only). @@ -99,7 +91,7 @@ public: /** Returns the checked or unchecked bitmap (Windows only). */ - wxBitmap GetBitmap(bool checked = @true); + wxBitmap GetBitmap(bool checked = true); /** Returns the font associated with the menu item (Windows only). @@ -120,7 +112,7 @@ public: Returns the text associated with the menu item including any accelerator characters that were passed to the constructor or SetItemLabel. - @sa GetItemLabelText(), GetLabelText() + @see GetItemLabelText(), GetLabelText() */ wxString GetItemLabel(); @@ -128,7 +120,7 @@ public: Returns the text associated with the menu item, without any accelerator characters. - @sa GetItemLabel(), GetLabelText() + @see GetItemLabel(), GetLabelText() */ wxString GetItemLabelText(); @@ -141,30 +133,30 @@ public: /** Returns the text associated with the menu item without any accelerator characters it might contain. - This function is deprecated in favour of GetItemLabelText(). - @sa GetText(), GetLabelFromText() + @see GetText(), GetLabelFromText() */ wxString GetLabel(); /** Strips all accelerator characters and mnemonics from the given @e text. For example, - will return just @c "Hello". + will return just @c "Hello". This function is deprecated; please use GetLabelText() instead. - @sa GetText(), GetLabel() + @see GetText(), GetLabel() */ static wxString GetLabelFromText(const wxString& text); /** Strips all accelerator characters and mnemonics from the given @e text. For example, + will return just @c "Hello". - @sa GetItemLabelText(), GetItemLabel() + @see GetItemLabelText(), GetItemLabel() */ static wxString GetLabelText(const wxString& text); @@ -181,7 +173,6 @@ public: /** Returns the text associated with the menu item. - @b NB: this function is deprecated, please use GetItemLabel() or GetItemLabelText() instead. @@ -196,10 +187,9 @@ public: /** Returns the text associated with the menu item, such as it was passed to the wxMenuItem constructor, i.e. with any accelerator characters it may contain. - This function is deprecated in favour of GetItemLabel(). - @sa GetLabel(), GetLabelFromText() + @see GetLabel(), GetLabelFromText() */ wxString GetText(); @@ -284,7 +274,6 @@ public: /** Sets the text associated with the menu item. - This function is deprecated in favour of SetItemLabel(). */ void SetText(const wxString& text); diff --git a/interface/metafile.h b/interface/metafile.h index a3d8444595..ced2a09fdc 100644 --- a/interface/metafile.h +++ b/interface/metafile.h @@ -52,7 +52,7 @@ public: metafile is returned, and ownership of it passes to the calling application (so it should be destroyed explicitly). */ - wxMetafile * Close(); + wxMetafile* Close(); }; @@ -92,19 +92,18 @@ public: /** Returns @true if the metafile is valid. */ -#define bool Ok() /* implementation is private */ + bool Ok(); /** Plays the metafile into the given device context, returning @true if successful. */ - bool Play(wxDC * dc); + bool Play(wxDC* dc); /** Passes the metafile data to the clipboard. The metafile can no longer be used for anything, but the wxMetafile object must still be destroyed by the application. - Below is a example of metafile, metafile device context and clipboard use from the @c hello.cpp example. Note the way the metafile dimensions are passed to the clipboard, making use of the device context's ability @@ -125,9 +124,9 @@ public: bounding box. The bounding box may be obtained from a device context after drawing into it, using the functions wxDC::MinX, wxDC::MinY, wxDC::MaxX and wxDC::MaxY. - In addition to adding the placeable metafile header, this function adds the equivalent of the following code to the start of the metafile data: + @code SetMapMode(dc, MM_ANISOTROPIC); SetWindowOrg(dc, minX, minY); @@ -135,17 +134,14 @@ public: @endcode This simulates the wxMM_TEXT mapping mode, which wxWidgets assumes. - Placeable metafiles may be imported by many Windows applications, and can be used in RTF (Rich Text Format) files. - - @e scale allows the specification of scale for the metafile. - + @a scale allows the specification of scale for the metafile. This function is only available under Windows. */ bool wxMakeMetafilePlaceable(const wxString& filename, int minX, int minY, int maxX, int maxY, - float scale=1.0); + float scale = 1.0); diff --git a/interface/mimetype.h b/interface/mimetype.h index 81b72d4991..70d72c0fcc 100644 --- a/interface/mimetype.h +++ b/interface/mimetype.h @@ -59,15 +59,13 @@ public: /** This function may be used to provide hard-wired fallbacks for the MIME types and extensions that might not be present in the system MIME database. - Please see the typetest sample for an example of using it. */ - void AddFallbacks(const wxFileTypeInfo * fallbacks); + void AddFallbacks(const wxFileTypeInfo* fallbacks); /** NB: You won't normally need to use more than one wxMimeTypesManager object in a program. - @ref ctor() wxMimeTypesManager @ref dtor() ~wxMimeTypesManager @@ -78,8 +76,7 @@ public: Gather information about the files with given extension and return the corresponding wxFileType object or @NULL if the extension is unknown. - - The @e extension parameter may have, or not, the leading dot, if it has it, + The @a extension parameter may have, or not, the leading dot, if it has it, it is stripped automatically. It must not however be empty. */ wxFileType* GetFileTypeFromExtension(const wxString& extension); @@ -96,7 +93,6 @@ public: to call them) and provide some useful operations for string representations of MIME types. Their usage is recommended instead of directly working with MIME types using wxString functions. - IsOfType() */ @@ -105,7 +101,6 @@ public: @b Unix: These functions may be used to load additional files (except for the default ones which are loaded automatically) containing MIME information in either mailcap(5) or mime.types(5) format. - ReadMailcap() ReadMimeTypes() @@ -115,11 +110,10 @@ public: /** - This function returns @true if either the given @e mimeType is exactly the - same as @e wildcard or if it has the same category and the subtype of - @e wildcard is '*'. Note that the '*' wildcard is not allowed in - @e mimeType itself. - + This function returns @true if either the given @a mimeType is exactly the + same as @a wildcard or if it has the same category and the subtype of + @a wildcard is '*'. Note that the '*' wildcard is not allowed in + @a mimeType itself. The comparison don by this function is case insensitive so it is not necessary to convert the strings to the same case before calling it. */ @@ -131,7 +125,6 @@ public: from either file extension or MIME type. If the function is successful, it returns a pointer to the wxFileType object which @b must be deleted by the caller, otherwise @NULL will be returned. - GetFileTypeFromMimeType() GetFileTypeFromExtension() @@ -142,23 +135,20 @@ public: Load additional file containing information about MIME types and associated information in mailcap format. See metamail(1) and mailcap(5) for more information. - - @e fallback parameter may be used to load additional mailcap files without + @a fallback parameter may be used to load additional mailcap files without overriding the settings found in the standard files: normally, entries from files loaded with ReadMailcap will override the entries from files loaded previously (and the standard ones are loaded in the very beginning), but this will not happen if this parameter is set to @true (default is @false). - The return value is @true if there were no errors in the file or @false otherwise. */ - bool ReadMailcap(const wxString& filename, bool fallback = @false); + bool ReadMailcap(const wxString& filename, bool fallback = false); /** Load additional file containing information about MIME types and associated information in mime.types file format. See metamail(1) and mailcap(5) for more information. - The return value is @true if there were no errors in the file or @false otherwise. */ @@ -223,36 +213,28 @@ public: This function is primarily intended for GetOpenCommand and GetPrintCommand usage but may be also used by the application directly if, for example, you want to use some non-default command to open the file. - The function replaces all occurrences of - format specification - with %s - the full file name %t - the MIME type %{param} - the value of the parameter @e param using the MessageParameters object you pass to it. - If there is no '%s' in the command string (and the string is not empty), it is assumed that the command reads the data on stdin and so the effect is the same as " %s" were appended to the string. - Unlike all other functions of this class, there is no error return for this function. */ @@ -260,18 +242,17 @@ public: MessageParameters& params); /** - If the function returns @true, the string pointed to by @e desc is filled + If the function returns @true, the string pointed to by @a desc is filled with a brief description for this file type: for example, "text document" for the "text/plain" MIME type. */ bool GetDescription(wxString* desc); /** - If the function returns @true, the array @e extensions is filled + If the function returns @true, the array @a extensions is filled with all extensions associated with this file type: for example, it may contain the following two elements for the MIME type "text/html" (notice the absence of the leading dot): "html" and "htm". - @b Windows: This function is currently not implemented: there is no (efficient) way to retrieve associated extensions from the given MIME type on this platform, so it will only return @true if the wxFileType object was @@ -284,21 +265,18 @@ public: /** If the function returns @true, the @c iconLoc is filled with the location of the icon for this MIME type. A wxIcon may be - created from @e iconLoc later. - + created from @a iconLoc later. @b Windows: The function returns the icon shown by Explorer for the files of the specified type. - @b Mac: This function is not implemented and always returns @false. - @b Unix: MIME manager gathers information about icons from GNOME and KDE settings and thus GetIcon's success depends on availability of these desktop environments. */ - bool GetIcon(wxIconLocation * iconLoc); + bool GetIcon(wxIconLocation* iconLoc); /** - If the function returns @true, the string pointed to by @e mimeType is filled + If the function returns @true, the string pointed to by @a mimeType is filled with full MIME type specification for this file type: for example, "text/plain". */ bool GetMimeType(wxString* mimeType); @@ -315,12 +293,11 @@ public: //@{ /** With the first version of this method, if the @true is returned, the - string pointed to by @e command is filled with the command which must be + string pointed to by @a command is filled with the command which must be executed (see wxExecute) in order to open the file of the given type. In this case, the name of the file as well as any other parameters is retrieved from MessageParameters() class. - In the second case, only the filename is specified and the command to be used to open this kind of file is returned directly. An empty string is returned to indicate that an error occurred (typically meaning that there is no standard way @@ -332,7 +309,7 @@ public: //@} /** - If the function returns @true, the string pointed to by @e command is filled + If the function returns @true, the string pointed to by @a command is filled with the command which must be executed (see wxExecute) in order to print the file of the given type. The name of the file is retrieved from MessageParameters() class. @@ -347,7 +324,6 @@ public: they must specify the MIME type and the version of MIME used, but almost always they provide additional information about the message such as the original file name or the charset (for the text documents). - These parameters may be useful to the program used to open, edit, view or print the message, so, for example, an e-mail client program will have to pass them to this program. Because wxFileType itself can not know about these parameters, @@ -357,8 +333,10 @@ public: there are no other parameters. If you wish to supply additional parameters, you must derive your own class from MessageParameters and override GetParamValue() function, for example: + Now you only need to create an object of this class and pass it to, for example, GetOpenCommand() like this: + @b Windows: As only the file name is used by the program associated with the given extension anyhow (but no other message parameters), there is no need to ever derive from MessageParameters class for a Windows-only program. diff --git a/interface/minifram.h b/interface/minifram.h index bb92da3ae8..232c259bb9 100644 --- a/interface/minifram.h +++ b/interface/minifram.h @@ -59,35 +59,31 @@ public: Constructor, creating the window. @param parent - The window parent. This may be @NULL. If it is non-@NULL, the frame will - always be displayed on top of the parent window on Windows. - + The window parent. This may be @NULL. If it is non-@NULL, the frame will + always be displayed on top of the parent window on Windows. @param id - The window identifier. It may take a value of -1 to indicate a default value. - + The window identifier. It may take a value of -1 to indicate a default + value. @param title - The caption to be displayed on the frame's title bar. - + The caption to be displayed on the frame's title bar. @param pos - The window position. The value wxDefaultPosition indicates a default position, chosen by - either the windowing system or wxWidgets, depending on platform. - + The window position. The value wxDefaultPosition indicates a default position, + chosen by + either the windowing system or wxWidgets, depending on platform. @param size - The window size. The value wxDefaultSize indicates a default size, chosen by - either the windowing system or wxWidgets, depending on platform. - + The window size. The value wxDefaultSize indicates a default size, chosen by + either the windowing system or wxWidgets, depending on platform. @param style - The window style. See wxMiniFrame. - + The window style. See wxMiniFrame. @param name - The name of the window. This parameter is used to associate a name with the + The name of the window. This parameter is used to associate a name with the item, - allowing the application user to set Motif resource values for - individual windows. + allowing the application user to set Motif resource values for + individual windows. @remarks The frame behaves like a normal frame on non-Windows platforms. - @sa Create() + @see Create() */ wxMiniFrame(); wxMiniFrame(wxWindow* parent, wxWindowID id, diff --git a/interface/module.h b/interface/module.h index 13251841b8..ed39fec075 100644 --- a/interface/module.h +++ b/interface/module.h @@ -91,27 +91,24 @@ public: //@{ /** - Call this function from the constructor of the derived class. @e dep must be + Call this function from the constructor of the derived class. @a dep must be the CLASSINFO of a wxModule-derived class and the corresponding module will be loaded before and unloaded after this module. - The second version of this function allows a dependency to be added by name without access to the class info. This is useful when a module is declared entirely in a source file and there is no header for the declaration of the module needed by CLASSINFO, however errors are not detected until run-time, instead of compile-time, then. - Note that circular dependencies are detected and result in a fatal error. @param dep - The class information object for the dependent module. - + The class information object for the dependent module. @param classname - The class name of the dependent module. + The class name of the dependent module. */ - void AddDependency(wxClassInfo * dep); - void AddDependency(const char * classname); + void AddDependency(wxClassInfo* dep); + void AddDependency(const char* classname); //@} /** diff --git a/interface/msgdlg.h b/interface/msgdlg.h index 1c063cd142..c7a88ab7b6 100644 --- a/interface/msgdlg.h +++ b/interface/msgdlg.h @@ -26,81 +26,144 @@ public: Constructor. Use ShowModal() to show the dialog. @param parent - Parent window. - + Parent window. @param message - Message to show on the dialog. - + Message to show on the dialog. @param caption - The dialog caption. - + The dialog caption. @param style - A dialog style (bitlist) containing flags chosen from the following: + A dialog style (bitlist) containing flags chosen from the following: + + + + + + + + wxOK + + + + + Show an OK button. + + + + + + wxCANCEL + + + + Show a Cancel button. - wxOK - Show an OK button. - wxCANCEL + wxYES_NO - Show a Cancel button. - wxYES_NO - Show Yes and No buttons. + Show Yes and No buttons. - wxYES_DEFAULT - Used with wxYES_NO, makes Yes button the default - which is the default + + + wxYES_DEFAULT + + + + + Used with wxYES_NO, makes Yes button the default - which is the default behaviour. - wxNO_DEFAULT - Used with wxYES_NO, makes No button the default. - wxICON_EXCLAMATION + wxNO_DEFAULT - Shows an exclamation mark icon. - wxICON_HAND - Shows an error icon. + Used with wxYES_NO, makes No button the default. - wxICON_ERROR - Shows an error icon - the same as wxICON_HAND. - wxICON_QUESTION + wxICON_EXCLAMATION - Shows a question mark icon. - wxICON_INFORMATION - Shows an information (i) icon. + Shows an exclamation mark icon. + + + + + + wxICON_HAND + + + + + Shows an error icon. + + + + + + wxICON_ERROR - wxSTAY_ON_TOP - The message box stays on top of all other window, even those of the other - applications (Windows only). + Shows an error icon - the same as wxICON_HAND. + + + + + + wxICON_QUESTION + + + + + Shows a question mark icon. + + + + + + wxICON_INFORMATION + + + + + Shows an information (i) icon. + + + + + + wxSTAY_ON_TOP + + + + + The message box stays on top of all other window, even those of the other + applications (Windows only). @param pos - Dialog position. Not Windows. + Dialog position. Not Windows. */ wxMessageDialog(wxWindow* parent, const wxString& message, const wxString& caption = "Message box", - long style = wxOK | wxCANCEL, + long style = wxOK | wxCANCEL, const wxPoint& pos = wxDefaultPosition); /** @@ -125,7 +188,6 @@ public: /** Overrides the default labels of the OK and Cancel buttons. - Please see the remarks in SetYesNoLabels() documentation. */ @@ -133,7 +195,6 @@ public: /** Overrides the default label of the OK button. - Please see the remarks in SetYesNoLabels() documentation. */ @@ -141,7 +202,6 @@ public: /** Overrides the default labels of the Yes, No and Cancel buttons. - Please see the remarks in SetYesNoLabels() documentation. */ @@ -150,7 +210,6 @@ public: /** Overrides the default labels of the Yes and No buttons. - Notice that this function is not currently available on all platforms, so it may return @false to indicate that the labels couldn't be changed. If it returns @true (currently only under wxMac), the labels were set successfully. @@ -171,54 +230,46 @@ public: // ============================================================================ /** - General purpose message dialog. @e style may be a bit list of the + General purpose message dialog. @a style may be a bit list of the following identifiers: wxYES_NO - Puts Yes and No buttons on the message box. May be combined with wxCANCEL. wxCANCEL - Puts a Cancel button on the message box. May only be combined with wxYES_NO or wxOK. wxOK - Puts an Ok button on the message box. May be combined with wxCANCEL. wxICON_EXCLAMATION - Displays an exclamation mark symbol. wxICON_HAND - Displays an error symbol. wxICON_ERROR - Displays an error symbol - the same as wxICON_HAND. wxICON_QUESTION - Displays a question mark symbol. wxICON_INFORMATION - Displays an information symbol. The return value is one of: wxYES, wxNO, wxCANCEL, wxOK. - For example: + @code ... int answer = wxMessageBox("Quit program?", "Confirm", @@ -228,12 +279,12 @@ public: ... @endcode - @e message may contain newline characters, in which case the + @a message may contain newline characters, in which case the message will be split into separate lines, to cater for large messages. */ int wxMessageBox(const wxString& message, const wxString& caption = "Message", int style = wxOK, - wxWindow * parent = @NULL, + wxWindow* parent = NULL, int x = -1, int y = -1); diff --git a/interface/msgqueue.h b/interface/msgqueue.h index fa57761674..75b9b1978e 100644 --- a/interface/msgqueue.h +++ b/interface/msgqueue.h @@ -34,13 +34,12 @@ public: Returns @true if the object had been initialized successfully, @false if an error occurred. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** Add a message to this queue and signal the threads waiting for messages (i.e. the threads which called wxMessageQueue::Receive or wxMessageQueue::ReceiveTimeout). - This method is safe to call from multiple threads in parallel. */ wxMessageQueueError Post(T const& msg); @@ -48,21 +47,17 @@ public: /** Block until a message becomes available in the queue. Waits indefinitely long or until an error occurs. - The message is returned in @e msg. */ wxMessageQueueError Receive(T& msg); /** Block until a message becomes available in the queue, but no more than - @e timeout milliseconds has elapsed. - - If no message is available after @e timeout milliseconds then returns + @a timeout milliseconds has elapsed. + If no message is available after @a timeout milliseconds then returns @b wxMSGQUEUE_TIMEOUT. - - If @e timeout is 0 then checks for any messages present in the queue + If @a timeout is 0 then checks for any messages present in the queue and returns immediately without waiting. - The message is returned in @e msg. */ wxMessageQueueError ReceiveTimeout(long timeout, T& msg); diff --git a/interface/mstream.h b/interface/mstream.h index 939159252d..b6ac5e9074 100644 --- a/interface/mstream.h +++ b/interface/mstream.h @@ -21,10 +21,10 @@ class wxMemoryOutputStream : public wxOutputStream { public: /** - If @e data is @NULL, then it will initialize a new empty buffer which will + If @a data is @NULL, then it will initialize a new empty buffer which will grow if required. */ - wxMemoryOutputStream(char * data = @NULL, size_t length = 0); + wxMemoryOutputStream(char* data = NULL, size_t length = 0); /** Destructor. @@ -33,16 +33,16 @@ public: /** CopyTo allowed you to transfer data from the internal buffer of - wxMemoryOutputStream to an external buffer. @e len specifies the size of + wxMemoryOutputStream to an external buffer. @a len specifies the size of the buffer. */ - size_t CopyTo(char * buffer, size_t len); + size_t CopyTo(char* buffer, size_t len); /** Returns the pointer to the stream object used as an internal buffer for that stream. */ - wxStreamBuffer * GetOutputStreamBuffer(); + wxStreamBuffer* GetOutputStreamBuffer(); }; @@ -64,12 +64,11 @@ public: /** Creates a new read-only memory stream, initializing it with the data from the given input stream @e stream. - - The @e len argument specifies the amount of data to read from + The @a len argument specifies the amount of data to read from the @e stream. Setting it to @e wxInvalidOffset means that - the @e stream is to be read entirely (i.e. till the EOF is reached). + the @a stream is to be read entirely (i.e. till the EOF is reached). */ - wxMemoryInputStream(const char * data, size_t len); + wxMemoryInputStream(const char* data, size_t len); wxMemoryInputStream(const wxMemoryOutputStream& stream); wxMemoryInputStream(wxInputStream& stream, wxFileOffset len = wxInvalidOffset); @@ -84,5 +83,5 @@ public: Returns the pointer to the stream object used as an internal buffer for that stream. */ - wxStreamBuffer * GetInputStreamBuffer(); + wxStreamBuffer* GetInputStreamBuffer(); }; diff --git a/interface/msw/ole/activex.h b/interface/msw/ole/activex.h index 09cf99a918..5422158629 100644 --- a/interface/msw/ole/activex.h +++ b/interface/msw/ole/activex.h @@ -9,15 +9,15 @@ /** @class wxActiveXEvent @headerfile ole/activex.h wx/msw/ole/activex.h - + An event class for handling activex events passed from wxActiveXContainer. ActiveX events are basically a function call with the parameters passed through an array of wxVariants along with a return value that is a wxVariant itself. What type the parameters or return value are depends on the context (i.e. what the .idl specifies). - + Note that unlike the third party wxActiveX function names are not supported. - + @library{wxbase} @category{FIXME} */ @@ -55,24 +55,24 @@ public: /** @class wxActiveXContainer @headerfile ole/activex.h wx/msw/ole/activex.h - + wxActiveXContainer is a host for an activex control on Windows (and as such is a platform-specific class). Note that the HWND that the class contains is the actual HWND of the activex control so using dynamic events and connecting to wxEVT_SIZE, for example, will recieve the actual size message sent to the control. - + It is somewhat similar to the ATL class CAxWindow in operation. - + The size of the activex control's content is generally gauranteed to be that of the client size of the parent of this wxActiveXContainer. - + You can also process activex events through wxEVT_ACTIVEX or the corresponding message map macro EVT_ACTIVEX. - + @library{wxbase} @category{FIXME} - + @seealso wxActiveXEvent */ @@ -82,14 +82,12 @@ public: /** Creates this activex container. - @param parent - parent of this control. Must not be @NULL. - - @param iid - COM IID of pUnk to query. Must be a valid interface to an activex control. - - @param pUnk - Interface of activex control + @param parent + parent of this control. Must not be @NULL. + @param iid + COM IID of pUnk to query. Must be a valid interface to an activex control. + @param pUnk + Interface of activex control */ wxActiveXContainer(wxWindow* parent, REFIID iid, IUnknown* pUnk); }; diff --git a/interface/msw/ole/automtn.h b/interface/msw/ole/automtn.h index 8e4a970a49..1e3a2bafcd 100644 --- a/interface/msw/ole/automtn.h +++ b/interface/msw/ole/automtn.h @@ -9,31 +9,31 @@ /** @class wxAutomationObject @headerfile ole/automtn.h wx/msw/ole/automtn.h - + The @b wxAutomationObject class represents an OLE automation object containing a single data member, an IDispatch pointer. It contains a number of functions that make it easy to perform automation operations, and set and get properties. The class makes heavy use of the wxVariant class. - + The usage of these classes is quite close to OLE automation usage in Visual Basic. The API is high-level, and the application can specify multiple properties in a single string. The following example gets the current Excel instance, and if it exists, makes the active cell bold. - + @code wxAutomationObject excelObject; if (excelObject.GetInstance("Excel.Application")) excelObject.PutProperty("ActiveCell.Font.Bold", @true); @endcode - + Note that this class obviously works under Windows only. - + @library{wxcore} @category{misc} - + @seealso wxVariant */ @@ -45,7 +45,7 @@ public: the object is deleted. */ - wxAutomationObject(WXIDISPATCH* dispatchPtr = @NULL); + wxAutomationObject(WXIDISPATCH* dispatchPtr = NULL); /** Destructor. If the internal IDispatch pointer is non-null, it will be released. @@ -64,15 +64,14 @@ public: following lines are syntactically valid: - - Note that @e method can contain dot-separated property names, to save the + Note that @a method can contain dot-separated property names, to save the application needing to call GetProperty several times using several temporary objects. For example: */ wxVariant CallMethod(const wxString& method, int noArgs, wxVariant args[]); - wxVariant CallMethod(const wxString& method, ... ); + wxVariant CallMethod(const wxString& method, ... ); //@} /** @@ -92,7 +91,6 @@ public: IDispatch pointer to this object. Returns @true if a pointer was successfully retrieved, @false otherwise. - Note that this cannot cope with two instances of a given OLE object being active simultaneously, such as two copies of Excel running. Which object is referenced cannot @@ -102,20 +100,19 @@ public: /** Retrieves a property from this object, assumed to be a dispatch pointer, and - initialises @e obj with it. + initialises @a obj with it. To avoid having to deal with IDispatch pointers directly, use this function in preference to GetProperty() when retrieving objects from other objects. - Note that an IDispatch pointer is stored as a void* pointer in wxVariant objects. - @sa GetProperty() + @see GetProperty() */ bool GetObject(wxAutomationObject& obj, const wxString& property, int noArgs = 0, - wxVariant args[] = @NULL); + wxVariant args[] = NULL); //@{ /** @@ -129,14 +126,13 @@ public: following lines are syntactically valid: - - Note that @e property can contain dot-separated property names, to save the + Note that @a property can contain dot-separated property names, to save the application needing to call GetProperty several times using several temporary objects. */ wxVariant GetProperty(const wxString& property, int noArgs, wxVariant args[]); - wxVariant GetProperty(const wxString& property, ... ); + wxVariant GetProperty(const wxString& property, ... ); //@} /** @@ -145,29 +141,24 @@ public: It is not meant to be called directly by the application, but is used by other convenience functions. - @param member - The member function or property name. - - @param action - Bitlist: may contain DISPATCH_PROPERTYPUT, DISPATCH_PROPERTYPUTREF, - DISPATCH_METHOD. - - @param retValue - Return value (ignored if there is no return value) - - @param noArgs - Number of arguments in args or ptrArgs. - - @param args - If non-null, contains an array of variants. - - @param ptrArgs - If non-null, contains an array of constant pointers to variants. + @param member + The member function or property name. + @param action + Bitlist: may contain DISPATCH_PROPERTYPUT, DISPATCH_PROPERTYPUTREF, + DISPATCH_METHOD. + @param retValue + Return value (ignored if there is no return value) + @param noArgs + Number of arguments in args or ptrArgs. + @param args + If non-null, contains an array of variants. + @param ptrArgs + If non-null, contains an array of constant pointers to variants. @returns @true if the operation was successful, @false otherwise. @remarks Two types of argument array are provided, so that when possible - pointers are used for efficiency. + pointers are used for efficiency. */ bool Invoke(const wxString& member, int action, wxVariant& retValue, int noArgs, @@ -186,20 +177,18 @@ public: following lines are syntactically valid: - - Note that @e property can contain dot-separated property names, to save the + Note that @a property can contain dot-separated property names, to save the application needing to call GetProperty several times using several temporary objects. */ bool PutProperty(const wxString& property, int noArgs, wxVariant args[]); - bool PutProperty(const wxString& property, ... ); + bool PutProperty(const wxString& property, ... ); //@} /** Sets the IDispatch pointer. This function does not check if there is already an IDispatch pointer. - You may need to cast from IDispatch* to WXIDISPATCH* when calling this function. */ void SetDispatchPtr(WXIDISPATCH* dispatchPtr); diff --git a/interface/msw/registry.h b/interface/msw/registry.h index be3ccb58a4..5515b4443b 100644 --- a/interface/msw/registry.h +++ b/interface/msw/registry.h @@ -54,15 +54,15 @@ public: void Close(); /** - Creates the key. Will fail if the key already exists and @e bOkIfExists is + Creates the key. Will fail if the key already exists and @a bOkIfExists is @false. */ - bool Create(bool bOkIfExists = @true); + bool Create(bool bOkIfExists = true); /** Deletes the subkey with all of its subkeys/values recursively. */ - void DeleteKey(const wxChar * szKey); + void DeleteKey(const wxChar* szKey); /** Deletes this key and all of its subkeys and values recursively. @@ -72,7 +72,7 @@ public: /** Deletes the named value. */ - void DeleteValue(const wxChar * szKey); + void DeleteValue(const wxChar* szKey); /** Returns @true if the key exists. @@ -93,24 +93,21 @@ public: Gets information about the key. @param pnSubKeys - The number of subkeys. - + The number of subkeys. @param pnMaxKeyLen - The maximum length of the subkey name. - + The maximum length of the subkey name. @param pnValues - The number of values. - + The number of values. @param pnMaxValueLen - The maximum length of a value. + The maximum length of a value. */ - bool GetKeyInfo(size_t * pnSubKeys, size_t * pnValues, - size_t * pnMaxValueLen); + bool GetKeyInfo(size_t* pnSubKeys, size_t* pnValues, + size_t* pnMaxValueLen); /** Gets the name of the registry key. */ - wxString GetName(bool bShortPrefix = @true); + wxString GetName(bool bShortPrefix = true); /** Gets the next key. @@ -125,7 +122,7 @@ public: /** Returns @true if given subkey exists. */ - bool HasSubKey(const wxChar * szKey); + bool HasSubKey(const wxChar* szKey); /** Returns @true if any subkeys exist. @@ -135,7 +132,7 @@ public: /** Returns @true if the value exists. */ - bool HasValue(const wxChar * szValue); + bool HasValue(const wxChar* szValue); /** Returns @true if any values exist. @@ -163,30 +160,30 @@ public: /** Retrieves the numeric value. */ - bool QueryValue(const wxChar * szValue, wxString& strValue); - bool QueryValue(const wxChar * szValue, long * plValue); + bool QueryValue(const wxChar* szValue, wxString& strValue); + bool QueryValue(const wxChar* szValue, long* plValue); //@} /** Renames the key. */ - bool Rename(const wxChar * szNewName); + bool Rename(const wxChar* szNewName); /** Renames a value. */ - bool RenameValue(const wxChar * szValueOld, - const wxChar * szValueNew); + bool RenameValue(const wxChar* szValueOld, + const wxChar* szValueNew); //@{ /** - Sets the given @e szValue which must be numeric, string or binary depending + Sets the given @a szValue which must be numeric, string or binary depending on the overload used. If the value doesn't exist, it is created. */ - bool SetValue(const wxChar * szValue, long lValue); - bool SetValue(const wxChar * szValue, + bool SetValue(const wxChar* szValue, long lValue); + bool SetValue(const wxChar* szValue, const wxString& strValue); - bool SetValue(const wxChar * szValue, + bool SetValue(const wxChar* szValue, const wxMemoryBuffer& buf); //@} }; diff --git a/interface/notebook.h b/interface/notebook.h index a83726c0c0..7c1e6e70da 100644 --- a/interface/notebook.h +++ b/interface/notebook.h @@ -38,7 +38,7 @@ public: /** Constructor (used internally by wxWidgets only). */ - wxNotebookEvent(wxEventType eventType = wxEVT_@NULL, int id = 0, + wxNotebookEvent(wxEventType eventType = wxEVT_NULL, int id = 0, int sel = -1, int oldSel = -1); @@ -49,7 +49,6 @@ public: /** Returns the currently selected page, or -1 if none was selected. - @b NB: 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 @@ -122,27 +121,21 @@ public: //@{ /** Constructs a notebook control. - Note that sometimes you can reduce flicker by passing the wxCLIP_CHILDREN window style. @param parent - The parent window. Must be non-@NULL. - + The parent window. Must be non-@NULL. @param id - The window identifier. - + The window identifier. @param pos - The window position. - + The window position. @param size - The window size. - + The window size. @param style - The window style. See wxNotebook. - + The window style. See wxNotebook. @param name - The name of the control (used only under Motif). + The name of the control (used only under Motif). */ wxNotebook(); wxNotebook(wxWindow* parent, wxWindowID id, @@ -159,49 +152,43 @@ public: /** Adds a new page. - The call to this function may generate the page changing events. @param page - Specifies the new page. - + Specifies the new page. @param text - Specifies the text for the new page. - + Specifies the text for the new page. @param select - Specifies whether the page should be selected. - + Specifies whether the page should be selected. @param imageId - Specifies the optional image index for the new page. + Specifies the optional image index for the new page. @returns @true if successful, @false otherwise. @remarks Do not delete the page, it will be deleted by the notebook. - @sa InsertPage() + @see InsertPage() */ bool AddPage(wxNotebookPage* page, const wxString& text, - bool select = @false, + bool select = false, int imageId = -1); /** Cycles through the tabs. - The call to this function generates the page changing events. */ - void AdvanceSelection(bool forward = @true); + void AdvanceSelection(bool forward = true); /** Sets the image list for the page control and takes ownership of the list. - @sa wxImageList, SetImageList() + @see wxImageList, SetImageList() */ void AssignImageList(wxImageList* imageList); /** Changes the selection for the given page, returning the previous selection. - The call to this function does not generate the page changing events. This is the only difference with SetSelection(). See @ref overview_progevent "this topic" for more info. @@ -224,7 +211,6 @@ public: /** Deletes the specified page, and the associated window. - The call to this function generates the page changing events. */ bool DeletePage(size_t page); @@ -232,12 +218,12 @@ public: /** Returns the currently selected notebook page or @NULL. */ - wxWindow * GetCurrentPage(); + wxWindow* GetCurrentPage(); /** Returns the associated image list. - @sa wxImageList, SetImageList() + @see wxImageList, SetImageList() */ wxImageList* GetImageList(); @@ -268,7 +254,6 @@ public: /** Returns the currently selected page, or -1 if none was selected. - Note that this method may return either the previously or newly selected page when called from the @c EVT_NOTEBOOK_PAGE_CHANGED handler depending on the platform and so @@ -288,79 +273,106 @@ public: /** Returns the index of the tab at the specified position or @c wxNOT_FOUND - if none. If @e flags parameter is non-@NULL, the position of the point + if none. If @a flags parameter is non-@NULL, the position of the point inside the tab is returned as well. @param pt - Specifies the point for the hit test. - + Specifies the point for the hit test. @param flags - Return value for detailed information. One of the following values: + Return value for detailed information. One of the following values: + + + + + + + + wxBK_HITTEST_NOWHERE + + + + + There was no tab under this point. + - wxBK_HITTEST_NOWHERE - There was no tab under this point. - wxBK_HITTEST_ONICON + wxBK_HITTEST_ONICON - The point was over an icon (currently wxMSW only). - wxBK_HITTEST_ONLABEL + The point was over an icon (currently wxMSW only). - The point was over a label (currently wxMSW only). - wxBK_HITTEST_ONITEM - The point was over an item, but not on the label or icon. - wxBK_HITTEST_ONPAGE + wxBK_HITTEST_ONLABEL - The point was over a currently selected page, not over any tab. Note that this - flag is present only if wxNOT_FOUND is returned. + + + The point was over a label (currently wxMSW only). + + + + + + wxBK_HITTEST_ONITEM + + + + + The point was over an item, but not on the label or icon. + + + + + + wxBK_HITTEST_ONPAGE + + + + + The point was over a currently selected page, not over any tab. Note that + this flag is present only if wxNOT_FOUND is returned. @returns Returns the zero-based tab index or wxNOT_FOUND if there is no - tab is at the specified position. + tab is at the specified position. */ - int HitTest(const wxPoint& pt, long flags = @NULL); + int HitTest(const wxPoint& pt, long flags = NULL); /** Inserts a new page at the specified position. @param index - Specifies the position for the new page. - + Specifies the position for the new page. @param page - Specifies the new page. - + Specifies the new page. @param text - Specifies the text for the new page. - + Specifies the text for the new page. @param select - Specifies whether the page should be selected. - + Specifies whether the page should be selected. @param imageId - Specifies the optional image index for the new page. + Specifies the optional image index for the new page. @returns @true if successful, @false otherwise. @remarks Do not delete the page, it will be deleted by the notebook. - @sa AddPage() + @see AddPage() */ bool InsertPage(size_t index, wxNotebookPage* page, const wxString& text, - bool select = @false, + bool select = false, int imageId = -1); /** An event handler function, called when the page selection is changed. - @sa wxNotebookEvent + @see wxNotebookEvent */ void OnSelChange(wxNotebookEvent& event); @@ -373,26 +385,24 @@ public: Sets the image list for the page control. It does not take ownership of the image list, you must delete it yourself. - @sa wxImageList, AssignImageList() + @see wxImageList, AssignImageList() */ void SetImageList(wxImageList* imageList); /** Sets the amount of space around each page's icon and label, in pixels. - @b NB: The vertical padding cannot be changed in wxGTK. */ void SetPadding(const wxSize& padding); /** - Sets the image index for the given page. @e image is an index into + Sets the image index for the given page. @a image is an index into the image list which was set with SetImageList(). */ bool SetPageImage(size_t page, int image); /** Sets the width and height of the pages. - @b NB: This method is currently not implemented for wxGTK. */ void SetPageSize(const wxSize& size); @@ -404,13 +414,11 @@ public: /** Sets the selection for the given page, returning the previous selection. - The call to this function generates the page changing events. - This function is deprecated and should not be used in new code. Please use the ChangeSelection() function instead. - @sa GetSelection() + @see GetSelection() */ int SetSelection(size_t page); }; diff --git a/interface/notifmsg.h b/interface/notifmsg.h index bbe2ec7de1..7d6ecd94f6 100644 --- a/interface/notifmsg.h +++ b/interface/notifmsg.h @@ -27,9 +27,7 @@ public: //@{ /** , @b wxWindow*@e parent = @NULL, @b int@e flags = @c wxICON_INFORMATION) - Create a notification object with the given attributes. - See SetTitle(), SetMessage(), SetParent() and @@ -42,7 +40,6 @@ public: /** Hides the notification. - Returns @true if it was hidden or @false if it couldn't be done (e.g. on some systems automatically hidden notifications can't be hidden manually) @@ -54,7 +51,6 @@ public: notification. Valid values are @c wxICON_INFORMATION, @c wxICON_WARNING and @c wxICON_ERROR (notice that @c wxICON_QUESTION is not allowed here). - Some implementations of this class may not support the icons. */ void SetFlags(int flags); @@ -83,10 +79,9 @@ public: /** Show the notification to the user and hides it after timeout seconds pass. Special values @c Timeout_Auto and @c Timeout_Never can be - used here, notice that you shouldn't rely on @e timeout being exactly + used here, notice that you shouldn't rely on @a timeout being exactly respected because the current platform may only support default timeout value and also because the user may be able to close the notification. - Returns @false if an error occurred. */ bool Show(int timeout = Timeout_Auto); diff --git a/interface/numdlg.h b/interface/numdlg.h index 1413cd8315..dca6c50834 100644 --- a/interface/numdlg.h +++ b/interface/numdlg.h @@ -8,14 +8,12 @@ /** Shows a dialog asking the user for numeric input. The dialogs title is set to -@e caption, it contains a (possibly) multiline @e message above the -single line @e prompt and the zone for entering the number. - -The number entered must be in the range @e min..@e max (both of which -should be positive) and @e value is the initial value of it. If the user +@e caption, it contains a (possibly) multiline @a message above the +single line @a prompt and the zone for entering the number. +The number entered must be in the range @e min..@a max (both of which +should be positive) and @a value is the initial value of it. If the user enters an invalid value or cancels the dialog, the function will return -1. - -Dialog is centered on its @e parent unless an explicit position is given in +Dialog is centered on its @a parent unless an explicit position is given in @e pos. */ long wxGetNumberFromUser(const wxString& message, @@ -24,7 +22,7 @@ long wxGetNumberFromUser(const wxString& message, long value, long min = 0, long max = 100, - wxWindow * parent = @NULL, + wxWindow* parent = NULL, const wxPoint& pos = wxDefaultPosition); diff --git a/interface/object.h b/interface/object.h index 67652cbd5a..32f85b35aa 100644 --- a/interface/object.h +++ b/interface/object.h @@ -40,7 +40,6 @@ public: Decrements the reference count associated with this shared data and, if it reaches zero, destroys this instance of wxObjectRefData releasing its memory. - Please note that after calling this function, the caller should absolutely avoid to use the pointer to this instance since it may not be valid anymore. @@ -85,8 +84,7 @@ public: @category{rtti} @seealso - wxClassInfo, @ref overview_debuggingoverview "Debugging overview", - wxObjectRefData + wxClassInfo, @ref overview_debuggingoverview, wxObjectRefData */ class wxObject { @@ -108,18 +106,17 @@ public: /** A virtual function that may be redefined by derived classes to allow dumping of memory states. - This function is only defined in debug build and doesn't exist at all if @c __WXDEBUG__ is not defined. @param stream - Stream on which to output dump information. + Stream on which to output dump information. @remarks Currently wxWidgets does not define Dump for derived classes, - but programmers may wish to use it for their own - applications. Be sure to call the Dump member of the - class's base class to allow all information to be - dumped. + but programmers may wish to use it for their own + applications. Be sure to call the Dump member of the + class's base class to allow all information to be + dumped. */ void Dump(ostream& stream); @@ -127,13 +124,13 @@ public: This virtual function is redefined for every class that requires run-time type information, when using DECLARE_CLASS macros. */ - wxClassInfo * GetClassInfo(); + wxClassInfo* GetClassInfo(); /** Returns the @b m_refData pointer. - @sa Ref(), UnRef(), wxObject::m_refData, SetRefData(), - wxObjectRefData + @see Ref(), UnRef(), wxObject::m_refData, SetRefData(), + wxObjectRefData */ wxObjectRefData* GetRefData(); @@ -142,18 +139,17 @@ public: the given class. @param info - A pointer to a class information object, which may be obtained - by using the CLASSINFO macro. + A pointer to a class information object, which may be obtained + by using the CLASSINFO macro. @returns @true if the class represented by info is the same class as this - one or is derived from it. + one or is derived from it. */ - bool IsKindOf(wxClassInfo * info); + bool IsKindOf(wxClassInfo* info); /** Returns @true if this object has the same data pointer as @e obj. Notice that @true is returned if the data pointers are @NULL in both objects. - This function only does a shallow comparison, i.e. it doesn't compare the objects pointed to by the data pointers of these objects. */ @@ -163,22 +159,22 @@ public: Makes this object refer to the data in @e clone. @param clone - The object to 'clone'. + The object to 'clone'. @remarks First this function calls UnRef() on itself to decrement - (and perhaps free) the data it is currently referring - to. + (and perhaps free) the data it is currently referring + to. - @sa UnRef(), wxObject::m_refData, SetRefData(), - GetRefData(), wxObjectRefData + @see UnRef(), wxObject::m_refData, SetRefData(), + GetRefData(), wxObjectRefData */ -#define void Ref(const wxObject& clone) /* implementation is private */ + void Ref(const wxObject& clone); /** Sets the @b m_refData pointer. - @sa Ref(), UnRef(), wxObject::m_refData, GetRefData(), - wxObjectRefData + @see Ref(), UnRef(), wxObject::m_refData, GetRefData(), + wxObjectRefData */ void SetRefData(wxObjectRefData* data); @@ -187,14 +183,13 @@ public: deletes the data. The @b m_refData member is set to @NULL. - @sa Ref(), wxObject::m_refData, SetRefData(), - GetRefData(), wxObjectRefData + @see Ref(), wxObject::m_refData, SetRefData(), + GetRefData(), wxObjectRefData */ void UnRef(); /** Ensure that this object's data is not shared with any other object. - if we have no data, it is created using CreateRefData() below, if we have shared data it is copied using CloneRefData(), otherwise nothing is done. @@ -203,11 +198,10 @@ public: /** wxObjectRefData* m_refData - Pointer to an object which is the object's reference-counted data. - @sa Ref(), UnRef(), SetRefData(), - GetRefData(), wxObjectRefData + @see Ref(), UnRef(), SetRefData(), + GetRefData(), wxObjectRefData */ @@ -225,8 +219,8 @@ public: the identifier __WXDEBUG__ is defined. It takes over memory allocation, allowing wxDebugContext operations. */ - void * new(size_t size, const wxString& filename = @NULL, - int lineNum = 0); + void* new(size_t size, const wxString& filename = NULL, + int lineNum = 0); }; @@ -252,9 +246,9 @@ public: objects of this class, so there is no need to create such objects explicitly in an application. */ - wxClassInfo(const wxChar * className, - const wxClassInfo * baseClass1, - const wxClassInfo * baseClass2, + wxClassInfo(const wxChar* className, + const wxClassInfo* baseClass1, + const wxClassInfo* baseClass2, int size, wxObjectConstructorFn fn); /** @@ -267,22 +261,22 @@ public: /** Finds the wxClassInfo object for a class of the given string name. */ - static wxClassInfo * FindClass(wxChar * name); + static wxClassInfo* FindClass(wxChar* name); /** Returns the name of the first base class (@NULL if none). */ - wxChar * GetBaseClassName1(); + wxChar* GetBaseClassName1(); /** Returns the name of the second base class (@NULL if none). */ - wxChar * GetBaseClassName2(); + wxChar* GetBaseClassName2(); /** Returns the string form of the class name. */ - wxChar * GetClassName(); + wxChar* GetClassName(); /** Returns the size of the class. @@ -336,10 +330,10 @@ public: //@{ /** This copy constructor increases the count of the reference - counted object to which @e tocopy points and then this + counted object to which @a tocopy points and then this class will point to, as well. */ - wxObjectDataPtrT(T* ptr = @NULL); + wxObjectDataPtrT(T* ptr = NULL); wxObjectDataPtrT(const wxObjectDataPtr& tocopy); //@} @@ -401,8 +395,8 @@ public: Used inside a class declaration to declare that the class should be made known to the class hierarchy, but objects of this class cannot be created dynamically. The same as DECLARE_CLASS. - Example: + @code class wxCommand: public wxObject { @@ -420,13 +414,13 @@ public: /** Returns a pointer to the wxClassInfo object associated with this class. */ -#define wxClassInfo * CLASSINFO() /* implementation is private */ +#define wxClassInfo* CLASSINFO() /* implementation is private */ /** Same as @c reinterpret_castT(x) if the compiler supports reinterpret cast or @c (T)x for old compilers. - @sa wx_const_cast, wx_static_cast + @see wx_const_cast, wx_static_cast */ T wx_reinterpret_cast(); @@ -441,15 +435,15 @@ T wx_reinterpret_cast(); This macro expands into @c const_castclassname *(ptr) if the compiler supports @e const_cast or into an old, C-style cast, otherwise. - @sa wx_const_cast, wxDynamicCast, wxStaticCast + @see wx_const_cast, wxDynamicCast, wxStaticCast */ -classname * wxConstCast(); +classname* wxConstCast(); /** Used in a C++ implementation file to complete the declaration of a class that has run-time type information. The same as IMPLEMENT_CLASS. - Example: + @code IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject) @@ -474,9 +468,9 @@ classname * wxConstCast(); tests whether @c this pointer is non-@NULL which is always @true), so this macro should be used to avoid them. - @sa wxDynamicCast + @see wxDynamicCast */ -classname * wxDynamicCastThis(); +classname* wxDynamicCastThis(); /** Used in a C++ implementation file to complete the declaration of @@ -491,7 +485,7 @@ classname * wxDynamicCastThis(); registered with the dynamic class system using DECLARE... and IMPLEMENT... macros. */ -wxObject * wxCreateDynamicObject(const wxString& className); +wxObject* wxCreateDynamicObject(const wxString& className); /** Used inside a class declaration to make the class known to wxWidgets RTTI @@ -499,8 +493,8 @@ wxObject * wxCreateDynamicObject(const wxString& className); creatable from run-time type information. Notice that this implies that the class should have a default constructor, if this is not the case consider using DECLARE_CLASS. - Example: + @code class wxFrame: public wxWindow { @@ -521,7 +515,7 @@ wxObject * wxCreateDynamicObject(const wxString& className); the cast it to the type @e T and not to @c T * and also the order of arguments is the same as for the standard cast. - @sa wx_reinterpret_cast, wx_static_cast + @see wx_reinterpret_cast, wx_static_cast */ T wx_const_cast(); @@ -537,11 +531,10 @@ T wx_const_cast(); the pointer is of this type (the check is done during the run-time) or @NULL otherwise. Usage of this macro is preferred over obsoleted wxObject::IsKindOf() function. - The @e ptr argument may be @NULL, in which case @NULL will be returned. - Example: + @code wxWindow *win = wxWindow::FindFocus(); wxTextCtrl *text = wxDynamicCast(win, wxTextCtrl); @@ -555,14 +548,15 @@ T wx_const_cast(); } @endcode - @sa @ref overview_runtimeclassoverview "RTTI overview", wxDynamicCastThis, - wxConstCast, wxStaticCast + @see @ref overview_runtimeclassoverview "RTTI overview", wxDynamicCastThis, + wxConstCast, wxStaticCast */ -classname * wxDynamicCast(); +classname* wxDynamicCast(); /** This is defined in debug mode to be call the redefined new operator with filename and line number arguments. The definition is: + @code #define WXDEBUG_NEW new(__FILE__,__LINE__) @endcode @@ -576,9 +570,9 @@ classname * wxDynamicCast(); result if @c wxDynamicCast(ptr, classname) == @NULL) and then returns the result of executing an equivalent of @c static_castclassname *(ptr). - @sa wx_static_cast, wxDynamicCast, wxConstCast + @see wx_static_cast, wxDynamicCast, wxConstCast */ -classname * wxStaticCast(); +classname* wxStaticCast(); /** Same as @c static_castT(x) if the compiler supports static cast or @@ -587,7 +581,7 @@ classname * wxStaticCast(); the same as for the standard static cast, i.e. @e T is the full type name and star is not appended to it. - @sa wx_const_cast, wx_reinterpret_cast, wx_truncate_cast + @see wx_const_cast, wx_reinterpret_cast, wx_truncate_cast */ T wx_static_cast(); @@ -595,8 +589,8 @@ T wx_static_cast(); Used in a C++ implementation file to complete the declaration of a class that has run-time type information, and whose instances can be created dynamically. - Example: + @code IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow) diff --git a/interface/odcombo.h b/interface/odcombo.h index 5ee81f1683..14b85a248b 100644 --- a/interface/odcombo.h +++ b/interface/odcombo.h @@ -31,7 +31,7 @@ @endStyleTable @beginEventTable - @event{EVT_COMBOBOX(id\, func)}: + @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 value of selection. @@ -52,37 +52,29 @@ public: Constructor, creating and showing a owner-drawn combobox. @param parent - Parent window. Must not be @NULL. - + Parent window. Must not be @NULL. @param id - Window identifier. The value wxID_ANY indicates a default value. - + Window identifier. The value wxID_ANY indicates a default value. @param value - Initial selection string. An empty string indicates no selection. - + Initial selection string. An empty string indicates no selection. @param pos - Window position. - + Window position. @param size - Window size. If wxDefaultSize is specified then the window is sized - appropriately. - + Window size. If wxDefaultSize is specified then the window is + sized + appropriately. @param n - Number of strings with which to initialise the control. - + Number of strings with which to initialise the control. @param choices - An array of strings with which to initialise the control. - + An array of strings with which to initialise the control. @param style - Window style. See wxOwnerDrawnComboBox. - + Window style. See wxOwnerDrawnComboBox. @param validator - Window validator. - + Window validator. @param name - Window name. + Window name. - @sa Create(), wxValidator + @see Create(), wxValidator */ wxOwnerDrawnComboBox(); wxOwnerDrawnComboBox(wxWindow* parent, wxWindowID id, @@ -90,7 +82,7 @@ public: const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, int n = 0, - const wxString choices[] = @NULL, + const wxString choices[] = NULL, long style = 0, const wxValidator& validator = wxDefaultValidator, const wxString& name = "comboBox"); @@ -146,7 +138,6 @@ public: /** This method is used to draw the items background and, maybe, a border around it. - The base class version implements a reasonable default behaviour which consists in drawing the selected item with the standard background colour and drawing a border around the item if it is either selected or current. @@ -162,17 +153,14 @@ public: the item text is simply drawn, as if the control was a normal combobox. @param dc - The device context to use for drawing - + The device context to use for drawing @param rect - The bounding rectangle for the item being drawn (DC clipping - region is set to this rectangle before calling this function) - + The bounding rectangle for the item being drawn (DC clipping + region is set to this rectangle before calling this function) @param item - The index of the item to be drawn - + The index of the item to be drawn @param flags - Combines any of the following flag values: + Combines any of the following flag values: */ void OnDrawItem(wxDC& dc, const wxRect& rect, int item, int flags); @@ -180,7 +168,6 @@ public: /** The derived class may implement this method to return the height of the specified item (in pixels). - The default implementation returns text height, as if this control was a normal combobox. */ @@ -190,7 +177,6 @@ public: The derived class may implement this method to return the width of the specified item (in pixels). If -1 is returned, then the item text width is used. - The default implementation returns -1. */ wxCoord OnMeasureItemWidth(size_t item); diff --git a/interface/palette.h b/interface/palette.h index 0249292ab5..25dbe12930 100644 --- a/interface/palette.h +++ b/interface/palette.h @@ -42,21 +42,17 @@ public: red, blue or green component. @param palette - A pointer or reference to the palette to copy. - + A pointer or reference to the palette to copy. @param n - The number of indices in the palette. - + The number of indices in the palette. @param red - An array of red values. - + An array of red values. @param green - An array of green values. - + An array of green values. @param blue - An array of blue values. + An array of blue values. - @sa Create() + @see Create() */ wxPalette(); wxPalette(const wxPalette& palette); @@ -77,20 +73,17 @@ public: red, blue or green component. @param n - The number of indices in the palette. - + The number of indices in the palette. @param red - An array of red values. - + An array of red values. @param green - An array of green values. - + An array of green values. @param blue - An array of blue values. + An array of blue values. @returns @true if the creation was successful, @false otherwise. - @sa wxPalette() + @see wxPalette() */ bool Create(int n, const unsigned char* red, const unsigned char* green, @@ -105,17 +98,15 @@ public: Returns a pixel value (index into the palette) for the given RGB values. @param red - Red value. - + Red value. @param green - Green value. - + Green value. @param blue - Blue value. + Blue value. @returns The nearest palette index or wxNOT_FOUND for unexpected errors. - @sa GetRGB() + @see GetRGB() */ int GetPixel(unsigned char red, unsigned char green, unsigned char blue); @@ -124,29 +115,26 @@ public: Returns RGB values for a given palette index. @param pixel - The palette index. - + The palette index. @param red - Receives the red value. - + Receives the red value. @param green - Receives the green value. - + Receives the green value. @param blue - Receives the blue value. + Receives the blue value. @returns @true if the operation was successful. - @sa GetPixel() + @see GetPixel() */ -#define bool GetRGB(int pixel, const unsigned char* red, - const unsigned char* green, - const unsigned char* blue) /* implementation is private */ + bool GetRGB(int pixel, const unsigned char* red, + const unsigned char* green, + const unsigned char* blue); /** Returns @true if palette data is present. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** Assignment operator, using @ref overview_trefcount "reference counting". diff --git a/interface/panel.h b/interface/panel.h index 91662b9e1a..f11b7a65d8 100644 --- a/interface/panel.h +++ b/interface/panel.h @@ -39,28 +39,24 @@ public: Constructor. @param parent - The parent window. - + The parent window. @param id - An identifier for the panel. A value of -1 is taken to mean a default. - + An identifier for the panel. A value of -1 is taken to mean a default. @param pos - The panel position. The value wxDefaultPosition indicates a default position, chosen by - either the windowing system or wxWidgets, depending on platform. - + The panel position. The value wxDefaultPosition indicates a default position, + chosen by + either the windowing system or wxWidgets, depending on platform. @param size - The panel size. The value wxDefaultSize indicates a default size, chosen by - either the windowing system or wxWidgets, depending on platform. - + The panel size. The value wxDefaultSize indicates a default size, chosen by + either the windowing system or wxWidgets, depending on platform. @param style - The window style. See wxPanel. - + The window style. See wxPanel. @param name - Used to associate a name with the window, - allowing the application user to set Motif resource values for - individual dialog boxes. + Used to associate a name with the window, + allowing the application user to set Motif resource values for + individual dialog boxes. - @sa Create() + @see Create() */ wxPanel(); wxPanel(wxWindow* parent, wxWindowID id = wxID_ANY, @@ -97,7 +93,7 @@ public: Sends a wxInitDialogEvent, which in turn transfers data to the dialog via validators. - @sa wxInitDialogEvent + @see wxInitDialogEvent */ void InitDialog(); @@ -105,17 +101,16 @@ public: The default handler for wxEVT_SYS_COLOUR_CHANGED. @param event - The colour change event. + The colour change event. @remarks Changes the panel's colour to conform to the current settings - (Windows only). Add an event table entry for your - panel class if you wish the behaviour to be different - (such as keeping a user-defined background colour). - If you do override this function, call wxEvent::Skip - to propagate the notification to child windows and - controls. + (Windows only). Add an event table entry for your panel + class if you wish the behaviour to be different (such + as keeping a user-defined background colour). If you do + override this function, call wxEvent::Skip to propagate + the notification to child windows and controls. - @sa wxSysColourChangedEvent + @see wxSysColourChangedEvent */ void OnSysColourChanged(wxSysColourChangedEvent& event); @@ -126,7 +121,7 @@ public: In practice, if you call this method and the control has at least one child window, the focus will be given to the child window. - @sa wxFocusEvent, wxWindow::SetFocus + @see wxFocusEvent, wxWindow::SetFocus */ virtual void SetFocus(); diff --git a/interface/pen.h b/interface/pen.h index d6252a9831..42e360c1c8 100644 --- a/interface/pen.h +++ b/interface/pen.h @@ -52,100 +52,180 @@ public: Copy constructor, uses @ref overview_trefcount "reference counting". @param colour - A colour object. - + A colour object. @param colourName - A colour name. - + A colour name. @param width - Pen width. Under Windows, the pen width cannot be greater than 1 if - the style is wxDOT, wxLONG_DASH, wxSHORT_DASH, wxDOT_DASH, or wxUSER_DASH. - + Pen width. Under Windows, the pen width cannot be greater than 1 if + the style is wxDOT, wxLONG_DASH, wxSHORT_DASH, wxDOT_DASH, or wxUSER_DASH. @param stipple - A stipple bitmap. - + A stipple bitmap. @param pen - A pointer or reference to a pen to copy. - + A pointer or reference to a pen to copy. @param style - The style may be one of the following: + The style may be one of the following: + + + + + + + wxSOLID + + + + + Solid style. + + + + + + wxTRANSPARENT + + + + + No pen is used. + + + + + + wxDOT + + + + + Dotted style. + + + + + + wxLONG_DASH + + + + + Long dashed style. + + + + + + wxSHORT_DASH + + + + + Short dashed style. + + + + + + wxDOT_DASH + + + + + Dot and dash style. + + + + + + wxSTIPPLE + + + + + Use the stipple bitmap. + + + + + + wxUSER_DASH + + + + + Use the user dashes: see SetDashes(). + + + + + + wxBDIAGONAL_HATCH + + + + + Backward diagonal hatch. + + + - wxSOLID + wxCROSSDIAG_HATCH - Solid style. - wxTRANSPARENT - No pen is used. + Cross-diagonal hatch. - wxDOT - Dotted style. - wxLONG_DASH + wxFDIAGONAL_HATCH - Long dashed style. - wxSHORT_DASH - Short dashed style. + Forward diagonal hatch. - wxDOT_DASH - Dot and dash style. - wxSTIPPLE + wxCROSS_HATCH - Use the stipple bitmap. - wxUSER_DASH - Use the user dashes: see SetDashes(). + Cross hatch. - wxBDIAGONAL_HATCH - Backward diagonal hatch. - wxCROSSDIAG_HATCH + wxHORIZONTAL_HATCH - Cross-diagonal hatch. - wxFDIAGONAL_HATCH - Forward diagonal hatch. + Horizontal hatch. - wxCROSS_HATCH - Cross hatch. - wxHORIZONTAL_HATCH + wxVERTICAL_HATCH - Horizontal hatch. - wxVERTICAL_HATCH - Vertical hatch. + Vertical hatch. @remarks Different versions of Windows and different versions of other - platforms support very different subsets of the - styles above - there is no similarity even between - Windows95 and Windows98 - so handle with care. + platforms support very different subsets of the styles + above - there is no similarity even between Windows95 + and Windows98 - so handle with care. - @sa SetStyle(), SetColour(), SetWidth(), SetStipple() + @see SetStyle(), SetColour(), SetWidth(), SetStipple() */ wxPen(); wxPen(const wxColour& colour, int width = 1, @@ -161,11 +241,10 @@ public: more info. @remarks Although all remaining pens are deleted when the application - exits, the application should try to clean up all - pens itself. This is because wxWidgets cannot know if - a pointer to the pen object is stored in an - application data structure, and there is a risk of - double deletion. + exits, the application should try to clean up all pens + itself. This is because wxWidgets cannot know if a + pointer to the pen object is stored in an application + data structure, and there is a risk of double deletion. */ ~wxPen(); @@ -174,24 +253,24 @@ public: wxCAP_PROJECTING and @b wxCAP_BUTT. The default is @b wxCAP_ROUND. - @sa SetCap() + @see SetCap() */ int GetCap(); /** Returns a reference to the pen colour. - @sa SetColour() + @see SetColour() */ wxColour GetColour(); /** Gets an array of dashes (defined as char in X, DWORD under Windows). - @e dashes is a pointer to the internal array. Do not deallocate or store this + @a dashes is a pointer to the internal array. Do not deallocate or store this pointer. The function returns the number of dashes associated with this pen. - @sa SetDashes() + @see SetDashes() */ int GetDashes(wxDash** dashes); @@ -200,42 +279,42 @@ public: wxJOIN_ROUND and @b wxJOIN_MITER. The default is @b wxJOIN_ROUND. - @sa SetJoin() + @see SetJoin() */ int GetJoin(); /** Gets a pointer to the stipple bitmap. - @sa SetStipple() + @see SetStipple() */ wxBitmap* GetStipple(); /** Returns the pen style. - @sa wxPen(), SetStyle() + @see wxPen(), SetStyle() */ int GetStyle(); /** Returns the pen width. - @sa SetWidth() + @see SetWidth() */ int GetWidth(); /** Returns @true if the pen is initialised. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** Sets the pen cap style, which may be one of @b wxCAP_ROUND, @b wxCAP_PROJECTING and @b wxCAP_BUTT. The default is @b wxCAP_ROUND. - @sa GetCap() + @see GetCap() */ void SetCap(int capStyle); @@ -243,7 +322,7 @@ public: /** The pen's colour is changed to the given colour. - @sa GetColour() + @see GetColour() */ void SetColour(wxColour& colour); void SetColour(const wxString& colourName); @@ -258,7 +337,7 @@ public: deallocated by the calling application until the pen is deleted or this function is called with a @NULL array. - @sa GetDashes() + @see GetDashes() */ void SetDashes(int n, wxDash* dashes); @@ -267,28 +346,28 @@ public: and @b wxJOIN_MITER. The default is @b wxJOIN_ROUND. - @sa GetJoin() + @see GetJoin() */ void SetJoin(int join_style); /** Sets the bitmap for stippling. - @sa GetStipple() + @see GetStipple() */ void SetStipple(wxBitmap* stipple); /** Set the pen style. - @sa wxPen() + @see wxPen() */ void SetStyle(int style); /** Sets the pen width. - @sa GetWidth() + @see GetWidth() */ void SetWidth(int width); diff --git a/interface/pickerbase.h b/interface/pickerbase.h index 9c2f93140c..6e70150998 100644 --- a/interface/pickerbase.h +++ b/interface/pickerbase.h @@ -51,7 +51,7 @@ public: Very important: the contents of the text control could be containing an invalid representation of the entity which can be chosen through the picker (e.g. the user entered an invalid colour syntax because of a typo). Thus you should never parse the content of the textctrl to get the user's input; rather use the derived-class getter (e.g. wxColourPickerCtrl::GetColour, wxFilePickerCtrl::GetPath, etc). */ - wxTextCtrl * GetTextCtrl(); + wxTextCtrl* GetTextCtrl(); /** Returns the proportion value of the text control. @@ -86,7 +86,7 @@ public: /** Sets the picker control as growable when @c grow is @true. */ - void SetPickerCtrlGrowable(bool grow = @true); + void SetPickerCtrlGrowable(bool grow = true); /** Sets the proportion value of the picker. @@ -98,7 +98,7 @@ public: Sets the text control as growable when @c grow is @true. This function can be used only when HasTextCtrl() returns @true. */ - void SetTextCtrlGrowable(bool grow = @true); + void SetTextCtrlGrowable(bool grow = true); /** Sets the proportion value of the text control. diff --git a/interface/platform.h b/interface/platform.h index 1b3d69fc7c..8033275713 100644 --- a/interface/platform.h +++ b/interface/platform.h @@ -16,9 +16,9 @@ Same as wxCHECK_VERSION but also checks that /** This is a macro which evaluates to @true if the current wxWidgets version is at least major.minor.release. - For example, to test if the program is compiled with wxWidgets 2.2 or higher, the following can be done: + @code wxString s; #if wxCHECK_VERSION(2, 2, 0) @@ -35,7 +35,7 @@ wxString s; /** Returns 1 if the compiler being used to compile the code is Visual C++ - compiler version @e major or greater. Otherwise, and also if + compiler version @a major or greater. Otherwise, and also if the compiler is not Visual C++ at all, returns 0. */ #define bool wxCHECK_VISUALC_VERSION(major) /* implementation is private */ diff --git a/interface/platinfo.h b/interface/platinfo.h index cad17745ad..4f3d6a455b 100644 --- a/interface/platinfo.h +++ b/interface/platinfo.h @@ -42,17 +42,16 @@ public: /** Returns @true if the OS version is at least @c major.minor. - @sa GetOSMajorVersion(), GetOSMinorVersion(), - CheckToolkitVersion() + @see GetOSMajorVersion(), GetOSMinorVersion(), + CheckToolkitVersion() */ bool CheckOSVersion(int major, int minor); /** Returns @true if the toolkit version is at least @c major.minor. - @sa GetToolkitMajorVersion(), - GetToolkitMinorVersion(), - CheckOSVersion() + @see GetToolkitMajorVersion(), + GetToolkitMinorVersion(), CheckOSVersion() */ bool CheckToolkitVersion(int major, int minor); @@ -60,7 +59,7 @@ public: Returns the global wxPlatformInfo object, initialized with the values for the currently running platform. */ -#define static const wxPlatformInfo Get() /* implementation is private */ + static const wxPlatformInfo Get(); /** Converts the given string to a wxArchitecture enum value or to @@ -103,7 +102,7 @@ public: wxPlatformInfo instance. See wxGetOsVersion for more info. - @sa CheckOSVersion() + @see CheckOSVersion() */ int GetOSMajorVersion(); @@ -112,7 +111,7 @@ public: wxPlatformInfo instance. See wxGetOsVersion for more info. - @sa CheckOSVersion() + @see CheckOSVersion() */ int GetOSMinorVersion(); @@ -174,10 +173,9 @@ public: wxPlatformInfo instance. Note that if GetPortId() returns wxPORT_BASE, then this value is zero (unless externally modified with wxPlatformInfo::SetToolkitVersion); that is, no native toolkit is in use. - See wxAppTraits::GetToolkitVersion for more info. - @sa CheckToolkitVersion() + @see CheckToolkitVersion() */ int GetToolkitMajorVersion(); @@ -186,17 +184,16 @@ public: wxPlatformInfo instance. Note that if GetPortId() returns wxPORT_BASE, then this value is zero (unless externally modified with wxPlatformInfo::SetToolkitVersion); that is, no native toolkit is in use. - See wxAppTraits::GetToolkitVersion for more info. - @sa CheckToolkitVersion() + @see CheckToolkitVersion() */ int GetToolkitMinorVersion(); /** Returns @true if this instance is fully initialized with valid values. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** Returns @true if this wxPlatformInfo describes wxUniversal build. diff --git a/interface/print.h b/interface/print.h index 7d2cc584fe..5ad64366d1 100644 --- a/interface/print.h +++ b/interface/print.h @@ -37,7 +37,7 @@ public: /** Gets the print preview object associated with the control bar. */ - wxPrintPreview * GetPrintPreview(); + wxPrintPreview* GetPrintPreview(); /** Gets the current zoom setting in percent. @@ -51,33 +51,27 @@ public: /** Constructor. - The buttons parameter may be a combination of the following, using the bitwise 'or' operator. wxPREVIEW_PRINT - Create a print button. wxPREVIEW_NEXT - Create a next page button. wxPREVIEW_PREVIOUS - Create a previous page button. wxPREVIEW_ZOOM - Create a zoom control. wxPREVIEW_DEFAULT - Equivalent to a combination of wxPREVIEW_PREVIOUS, wxPREVIEW_NEXT and wxPREVIEW_ZOOM. */ @@ -176,7 +170,6 @@ public: Creates the preview canvas and control bar, and calls wxWindow::MakeModal(@true) to disable other top-level windows in the application. - This function should be called by the application prior to showing the frame. */ @@ -217,15 +210,12 @@ public: used for actual printing, and the address of an optional block of printer data, which will be copied to the print preview object's print data. - - If @e printoutForPrinting is non-@NULL, a @b Print... button will be placed on + If @a printoutForPrinting is non-@NULL, a @b Print... button will be placed on the preview frame so that the user can print directly from the preview interface. - Do not explicitly delete the printout objects once this destructor has been called, since they will be deleted in the wxPrintPreview constructor. - The same does not apply to the @e data argument. - + The same does not apply to the @a data argument. Test the Ok member to check whether the wxPrintPreview object was created correctly. Ok could return @false if there was a problem initializing the printer device @@ -234,7 +224,7 @@ public: */ wxPrintPreview(wxPrintout* printout, wxPrintout* printoutForPrinting, - wxPrintData* data=@NULL); + wxPrintData* data = NULL); /** Destructor. Deletes both print preview objects, so do not destroy these objects @@ -256,7 +246,7 @@ public: Gets the frame used for displaying the print preview canvas and control bar. */ - wxFrame * GetFrame(); + wxFrame* GetFrame(); /** Returns the maximum page number. @@ -271,14 +261,14 @@ public: /** Gets the preview printout object associated with the wxPrintPreview object. */ - wxPrintout * GetPrintout(); + wxPrintout* GetPrintout(); /** Gets the printout object to be used for printing from within the preview interface, or @NULL if none exists. */ - wxPrintout * GetPrintoutForPrinting(); + wxPrintout* GetPrintoutForPrinting(); /** Returns @true if the wxPrintPreview is valid, @false otherwise. It could return @@ -286,23 +276,21 @@ public: problem initializing the printer device context (current printer not set, for example). */ -#define bool Ok() /* implementation is private */ + bool Ok(); /** This refreshes the preview window with the preview image. It must be called from the preview window's OnPaint member. - The implementation simply blits the preview bitmap onto the canvas, creating a new preview bitmap if none exists. */ - bool PaintPage(wxPreviewCanvas * canvas, wxDC dc); + bool PaintPage(wxPreviewCanvas* canvas, wxDC dc); /** Invokes the print process using the second wxPrintout object supplied in the wxPrintPreview constructor. Will normally be called by the @b Print... panel item on the preview frame's control bar. - Returns @false in case of error -- call wxPrinter::GetLastError to get detailed information about the kind of the error. @@ -328,12 +316,12 @@ public: Sets the frame to be used for displaying the print preview canvas and control bar. */ - void SetFrame(wxFrame * frame); + void SetFrame(wxFrame* frame); /** Associates a printout object with the wxPrintPreview object. */ - void SetPrintout(wxPrintout * printout); + void SetPrintout(wxPrintout* printout); /** Sets the percentage preview zoom, and refreshes the preview canvas @@ -368,9 +356,9 @@ public: Constructor. Pass an optional pointer to a block of print dialog data, which will be copied to the printer object's local data. - @sa wxPrintDialogData, wxPrintData + @see wxPrintDialogData, wxPrintData */ - wxPrinter(wxPrintDialogData* data = @NULL); + wxPrinter(wxPrintDialogData* data = NULL); /** Creates the default printing abort window, with a cancel button. @@ -387,23 +375,18 @@ public: PrintDialog() or wxPrintPreview::Print. These functions set last error to @b wxPRINTER_NO_ERROR if no error happened. - Returned value is one of the following: - @b wxPRINTER_NO_ERROR - No error happened. @b wxPRINTER_CANCELLED - The user cancelled printing. @b wxPRINTER_ERROR - There was an error during printing. */ static wxPrinterError GetLastError(); @@ -419,15 +402,14 @@ public: object which controls the printing of a document, and whether the print dialog should be invoked first. - Print could return @false if there was a problem initializing the printer device context (current printer not set, for example) or the user cancelled printing. Call GetLastError() to get detailed information about the kind of the error. */ - bool Print(wxWindow * parent, wxPrintout * printout, - bool prompt=@true); + bool Print(wxWindow* parent, wxPrintout* printout, + bool prompt = true); /** Invokes the print dialog. If successful (the user did not press Cancel @@ -435,22 +417,21 @@ public: (otherwise @NULL is returned -- call GetLastError() to get detailed information about the kind of the error). - The application must delete this device context to avoid a memory leak. */ - wxDC* PrintDialog(wxWindow * parent); + wxDC* PrintDialog(wxWindow* parent); /** Default error-reporting function. */ - void ReportError(wxWindow * parent, wxPrintout * printout, + void ReportError(wxWindow* parent, wxPrintout* printout, const wxString& message); /** Invokes the print setup dialog. Note that the setup dialog is obsolete from Windows 95, though retained for backward compatibility. */ - bool Setup(wxWindow * parent); + bool Setup(wxWindow* parent); }; @@ -542,7 +523,7 @@ public: or Mac, a wxPostScriptDC if printing on other platforms, and a wxMemoryDC if previewing. */ -#define wxDC * GetDC() /* implementation is private */ + wxDC* GetDC(); /** Return the rectangle corresponding to the page margins specified by the given @@ -575,7 +556,7 @@ public: FitThisSizeToXXX() and MapScreenSizeToXXX routines below, which do most of the scaling calculations for you. */ - void GetPPIPrinter(int * w, int * h); + void GetPPIPrinter(int* w, int* h); /** Returns the number of pixels per logical inch of the screen device context. @@ -583,24 +564,23 @@ public: for drawing text onto the printer. If you are doing your own scaling, remember to multiply this by a scaling factor to take the preview DC size into account. */ - void GetPPIScreen(int * w, int * h); + void GetPPIScreen(int* w, int* h); /** Called by the framework to obtain information from the application about minimum and maximum page values that the user can select, and the required page range to be printed. By default this returns 1, 32000 for the page minimum and maximum values, and 1, 1 for the required page range. - - If @e minPage is zero, the page number controls in the print dialog will be + If @a minPage is zero, the page number controls in the print dialog will be disabled. */ - void GetPageInfo(int * minPage, int * maxPage, int * pageFrom, - int * pageTo); + void GetPageInfo(int* minPage, int* maxPage, int* pageFrom, + int* pageTo); /** Returns the size of the printer page in millimetres. */ - void GetPageSizeMM(int * w, int * h); + void GetPageSizeMM(int* w, int* h); /** Returns the size of the printer page in pixels, called the page rectangle. @@ -611,7 +591,7 @@ public: the current preview zoom. The application must take this discrepancy into account if previewing is to be supported. */ - void GetPageSizePixels(int * w, int * h); + void GetPageSizePixels(int* w, int* h); /** Returns the rectangle that corresponds to the entire paper in pixels, called the @@ -702,7 +682,6 @@ public: Called by the framework at the start of document printing. Return @false from this function cancels the print job. OnBeginDocument is called once for every copy printed. - The base OnBeginDocument() @e must be called (and the return value checked) from within the overridden function, since it calls wxDC::StartDoc. */ @@ -718,7 +697,6 @@ public: /** Called by the framework at the end of document printing. OnEndDocument is called once for every copy printed. - The base OnEndDocument() @e must be called from within the overridden function, since it calls wxDC::EndDoc. */ diff --git a/interface/printdlg.h b/interface/printdlg.h index 90c9c83b24..5560dec200 100644 --- a/interface/printdlg.h +++ b/interface/printdlg.h @@ -28,9 +28,9 @@ public: Constructor. Pass a parent window, and optionally a pointer to a block of print data, which will be copied to the print dialog's print data. - @sa wxPrintDialogData + @see wxPrintDialogData */ - wxPrintDialog(wxWindow* parent, wxPrintDialogData* data = @NULL); + wxPrintDialog(wxWindow* parent, wxPrintDialogData* data = NULL); /** Destructor. If GetPrintDC() has @e not been called, @@ -103,7 +103,7 @@ public: data, which will be copied to the print dialog's internal data. */ wxPageSetupDialog(wxWindow* parent, - wxPageSetupDialogData* data = @NULL); + wxPageSetupDialogData* data = NULL); /** Destructor. diff --git a/interface/process.h b/interface/process.h index ed62590367..d77a129e7e 100644 --- a/interface/process.h +++ b/interface/process.h @@ -47,30 +47,26 @@ class wxProcess : public wxEvtHandler public: //@{ /** - Constructs a process object. @e id is only used in the case you want to + Constructs a process object. @a id is only used in the case you want to use wxWidgets events. It identifies this object, or another window that will receive the event. - - If the @e parent parameter is different from @NULL, it will receive + If the @a parent parameter is different from @NULL, it will receive a wxEVT_END_PROCESS notification event (you should insert EVT_END_PROCESS macro in the event table of the parent to handle it) with the given @e id. - The second constructor creates an object without any associated parent (and - hence no id neither) but allows to specify the @e flags which can have the + hence no id neither) but allows to specify the @a flags which can have the value of @c wxPROCESS_DEFAULT or @c wxPROCESS_REDIRECT. Specifying the former value has no particular effect while using the latter one is equivalent to calling Redirect(). @param parent - The event handler parent. - + The event handler parent. @param id - id of an event. - + id of an event. @param flags - either wxPROCESS_DEFAULT or wxPROCESS_REDIRECT + either wxPROCESS_DEFAULT or wxPROCESS_REDIRECT */ - wxProcess(wxEvtHandler * parent = @NULL, int id = -1); + wxProcess(wxEvtHandler* parent = NULL, int id = -1); wxProcess(int flags); //@} @@ -103,7 +99,7 @@ public: /** Returns @true if the given process exists in the system. - @sa Kill(), @ref overview_sampleexec "Exec sample" + @see Kill(), @ref overview_sampleexec "Exec sample" */ static bool Exists(int pid); @@ -136,7 +132,7 @@ public: Returns @true if there is data to be read on the child process standard error stream. - @sa IsInputAvailable() + @see IsInputAvailable() */ bool IsErrorAvailable(); @@ -144,11 +140,10 @@ public: Returns @true if there is data to be read on the child process standard output stream. This allows to write simple (and extremely inefficient) polling-based code waiting for a better mechanism in future wxWidgets versions. - See the @ref overview_sampleexec "exec sample" for an example of using this function. - @sa IsInputOpened() + @see IsInputOpened() */ bool IsInputAvailable(); @@ -159,18 +154,17 @@ public: /** Send the specified signal to the given process. Possible signal values are: + @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning under both Unix and Windows but all the other signals are equivalent to @c wxSIGTERM under Windows. - - The @e flags parameter can be wxKILL_NOCHILDREN (the default), + The @a flags parameter can be wxKILL_NOCHILDREN (the default), or wxKILL_CHILDREN, in which case the child processes of this process will be killed too. Note that under Unix, for wxKILL_CHILDREN to work you should have created the process passing wxEXEC_MAKE_GROUP_LEADER. - Returns the element of @c wxKillError enum: - @sa Exists(), wxKill, @ref overview_sampleexec "Exec sample" + @see Exists(), wxKill, @ref overview_sampleexec "Exec sample" */ static wxKillError Kill(int pid, wxSignal signal = wxSIGNONE, int flags = wxKILL_NOCHILDREN); @@ -182,19 +176,17 @@ public: It raises a wxWidgets event when it isn't overridden. pid - The pid of the process which has just terminated. - + The pid of the process which has just terminated. @param status - The exit code of the process. + The exit code of the process. */ void OnTerminate(int pid, int status); /** This static method replaces the standard @c popen() function: it launches - the process specified by the @e cmd parameter and returns the wxProcess + the process specified by the @a cmd parameter and returns the wxProcess object which can be used to retrieve the streams connected to the standard input, output and error output of the child process. - If the process couldn't be launched, @NULL is returned. Note that in any case the returned pointer should @b not be deleted, rather the process object will be destroyed automatically when the child process terminates. This @@ -202,18 +194,17 @@ public: exits to avoid memory leaks. @param cmd - The command to execute, including optional arguments. - + The command to execute, including optional arguments. @param flags - The flags to pass to wxExecute. - NOTE: wxEXEC_SYNC should not be used. + The flags to pass to wxExecute. + NOTE: wxEXEC_SYNC should not be used. @returns A pointer to new wxProcess object or @NULL on error. - @sa wxExecute + @see wxExecute */ - static wxProcess * Open(const wxString& cmd, - int flags = wxEXEC_ASYNC); + static wxProcess* Open(const wxString& cmd, + int flags = wxEXEC_ASYNC); /** Turns on redirection. wxExecute will try to open a couple of pipes @@ -235,7 +226,7 @@ public: @category{events} @seealso - wxProcess, @ref overview_eventhandlingoverview "Event handling overview" + wxProcess, @ref overview_eventhandlingoverview */ class wxProcessEvent : public wxEvent { diff --git a/interface/progdlg.h b/interface/progdlg.h index 22199fec75..6fd996201e 100644 --- a/interface/progdlg.h +++ b/interface/progdlg.h @@ -53,23 +53,19 @@ public: window only. @param title - Dialog title to show in titlebar. - + Dialog title to show in titlebar. @param message - Message displayed above the progress bar. - + Message displayed above the progress bar. @param maximum - Maximum value for the progress bar. - + Maximum value for the progress bar. @param parent - Parent window. - + Parent window. @param style - The dialog style. See wxProgressDialog. + The dialog style. See wxProgressDialog. */ wxProgressDialog(const wxString& title, const wxString& message, int maximum = 100, - wxWindow * parent = @NULL, + wxWindow* parent = NULL, int style = wxPD_AUTO_HIDE | wxPD_APP_MODAL); /** @@ -85,7 +81,7 @@ public: the progress bar a bit to indicate that some progress was done. */ virtual bool Pulse(const wxString& newmsg = "", - bool * skip = @NULL); + bool* skip = NULL); /** Can be used to continue with the dialog, after the user had chosen @@ -97,25 +93,23 @@ public: Updates the dialog, setting the progress bar to the new value and, if given changes the message above it. Returns @true unless the Cancel button has been pressed. - If @false is returned, the application can either immediately destroy the dialog or ask the user for the confirmation and if the abort is not confirmed the dialog may be resumed with Resume() function. @param value - The new value of the progress meter. It should be less than or - equal to the maximum value given to the constructor and the dialog is closed if - it is equal to the maximum. - + The new value of the progress meter. It should be less than or + equal to the maximum value given to the constructor and the dialog is + closed if + it is equal to the maximum. @param newmsg - The new messages for the progress dialog text, if it is - empty (which is the default) the message is not changed. - + The new messages for the progress dialog text, if it is + empty (which is the default) the message is not changed. @param skip - If "Skip" button was pressed since last - Update call, this is set to @true. + If "Skip" button was pressed since last + Update call, this is set to @true. */ virtual bool Update(int value, const wxString& newmsg = "", - bool * skip = @NULL); + bool* skip = NULL); }; diff --git a/interface/propdlg.h b/interface/propdlg.h index b86f54ee7d..11642b28ee 100644 --- a/interface/propdlg.h +++ b/interface/propdlg.h @@ -104,7 +104,7 @@ public: wxDialog::CreateButtonSizer, and the flags are the same. On PocketPC, no buttons are created. */ - void CreateButtons(int flags=wxOK|wxCANCEL); + void CreateButtons(int flags = wxOK|wxCANCEL); /** Returns the book control that will contain your settings pages. @@ -127,7 +127,7 @@ public: dialog will be shown full-screen, and the layout will be done when the dialog receives a size event. */ - void LayoutDialog(int centreFlags=wxBOTH); + void LayoutDialog(int centreFlags = wxBOTH); /** Sets the book control used for the dialog. You will normally not need to use @@ -146,41 +146,33 @@ public: It is a bit list of the following values: - wxPROPSHEET_DEFAULT - Uses the default look and feel for the controller window, normally a notebook except on Smartphone where a choice control is used. wxPROPSHEET_NOTEBOOK - Uses a notebook for the controller window. wxPROPSHEET_TOOLBOOK - Uses a toolbook for the controller window. wxPROPSHEET_CHOICEBOOK - Uses a choicebook for the controller window. wxPROPSHEET_LISTBOOK - Uses a listbook for the controller window. wxPROPSHEET_TREEBOOK - Uses a treebook for the controller window. wxPROPSHEET_SHRINKTOFIT - Shrinks the dialog window to fit the currently selected page (common behaviour for property sheets on Mac OS X). diff --git a/interface/protocol/ftp.h b/interface/protocol/ftp.h index d98d55879c..46c531dc76 100644 --- a/interface/protocol/ftp.h +++ b/interface/protocol/ftp.h @@ -84,12 +84,12 @@ public: /** Default constructor. */ -#define wxFTP() /* implementation is private */ + wxFTP(); /** Destructor will close the connection if connected. */ -#define ~wxFTP() /* implementation is private */ + ~wxFTP(); /** Aborts the download currently in process, returns @true if ok, @false @@ -104,7 +104,7 @@ public: bool ChDir(const wxString& dir); /** - Send the specified @e command to the FTP server. @e ret specifies + Send the specified @a command to the FTP server. @a ret specifies the expected result. @returns @true if the command has been sent successfully, else @false. @@ -118,16 +118,17 @@ public: /** The GetList function is quite low-level. It returns the list of the files in - the current directory. The list can be filtered using the @e wildcard string. - If @e wildcard is empty (default), it will return all files in directory. - + the current directory. The list can be filtered using the @a wildcard string. + If @a wildcard is empty (default), it will return all files in directory. The form of the list can change from one peer system to another. For example, for a UNIX peer system, it will look like this: + But on Windows system, it will look like this: + Return value: @true if the file list was successfully retrieved, @false otherwise. - @sa GetFilesList() + @see GetFilesList() */ bool GetDirList(wxArrayString& files, const wxString& wildcard = ""); @@ -145,7 +146,6 @@ public: directory (optionally only of the files matching the @e wildcard, all files by default). This list always has the same format and contains one full (including the directory path) file name per line. - Return value: @true if the file list was successfully retrieved, @false otherwise. */ @@ -160,9 +160,9 @@ public: You will be notified when the EOF is reached by an error. @returns Returns @NULL if an error occurred (it could be a network failure - or the fact that the file doesn't exist). + or the fact that the file doesn't exist). */ - wxInputStream * GetInputStream(const wxString& path); + wxInputStream* GetInputStream(const wxString& path); /** Returns the last command result, i.e. the full server reply for the last @@ -177,9 +177,9 @@ public: @returns An initialized write-only stream. - @sa wxOutputStream + @see wxOutputStream */ - wxOutputStream * GetOutputStream(const wxString& file); + wxOutputStream* GetOutputStream(const wxString& file); /** Create the specified directory in the current FTP working directory. @@ -190,10 +190,10 @@ public: /** Returns the current FTP working directory. */ -#define wxString Pwd() /* implementation is private */ + wxString Pwd(); /** - Rename the specified @e src element to @e dst. Returns @true if successful. + Rename the specified @a src element to @e dst. Returns @true if successful. */ bool Rename(const wxString& src, const wxString& dst); @@ -209,7 +209,7 @@ public: bool RmFile(const wxString& path); /** - Send the specified @e command to the FTP server and return the first + Send the specified @a command to the FTP server and return the first character of the return code. */ char SendCommand(const wxString& command); @@ -225,7 +225,7 @@ public: bool SetBinary(); /** - If @e pasv is @true, passive connection to the FTP server is used. This is + If @a pasv is @true, passive connection to the FTP server is used. This is the default as it works with practically all firewalls. If the server doesn't support passive move, you may call this function with @false argument to use active connection. @@ -240,7 +240,6 @@ public: /** Sets the transfer mode to the specified one. It will be used for the next transfer. - If this function is never called, binary transfer mode is used by default. */ bool SetTransferMode(TransferMode mode); diff --git a/interface/protocol/http.h b/interface/protocol/http.h index 8dd641eaeb..0a14fab982 100644 --- a/interface/protocol/http.h +++ b/interface/protocol/http.h @@ -30,7 +30,6 @@ public: /** Creates a new input stream on the specified path. Notice that this stream is unseekable, i.e. SeekI() and TellI() methods shouldn't be used. - Note that you can still know the size of the file you are getting using wxStreamBase::GetSize. However there is a limitation: in HTTP protocol, the size is not always specified so sometimes @@ -39,16 +38,16 @@ public: method in a loop to get the total size. @returns Returns the initialized stream. You must delete it yourself once - you don't use it anymore and this must be done before - the wxHTTP object itself is destroyed. The destructor - closes the network connection. The next time you will - try to get a file the network connection will have to - be reestablished, but you don't have to take care of - this since wxHTTP reestablishes it automatically. + you don't use it anymore and this must be done before + the wxHTTP object itself is destroyed. The destructor + closes the network connection. The next time you will + try to get a file the network connection will have to + be reestablished, but you don't have to take care of + this since wxHTTP reestablishes it automatically. - @sa wxInputStream + @see wxInputStream */ - wxInputStream * GetInputStream(const wxString& path); + wxInputStream* GetInputStream(const wxString& path); /** Returns the HTTP response code returned by the server. Please refer to @@ -59,7 +58,7 @@ public: /** It sets data of a field to be sent during the next request to the HTTP server. The field - name is specified by @e header and the content by @e h_data. + name is specified by @a header and the content by @e h_data. This is a low level function and it assumes that you know what you are doing. */ void SetHeader(const wxString& header, const wxString& h_data); diff --git a/interface/protocol/protocol.h b/interface/protocol/protocol.h index 522c18a14b..aaab5c0df1 100644 --- a/interface/protocol/protocol.h +++ b/interface/protocol/protocol.h @@ -35,55 +35,44 @@ public: /** Returns the last occurred error. - @b wxPROTO_NOERR - No error. @b wxPROTO_NETERR - A generic network error occurred. @b wxPROTO_PROTERR - An error occurred during negotiation. @b wxPROTO_CONNERR - The client failed to connect the server. @b wxPROTO_INVVAL - Invalid value. @b wxPROTO_NOHNDLR - . @b wxPROTO_NOFILE - The remote file doesn't exist. @b wxPROTO_ABRT - Last action aborted. @b wxPROTO_RCNCT - An error occurred during reconnection. @b wxPROTO_STREAM - Someone tried to send a command during a transfer. */ wxProtocolError GetError(); @@ -96,12 +85,12 @@ public: You will be notified when the EOF is reached by an error. @returns Returns the initialized stream. You will have to delete it - yourself once you don't use it anymore. The - destructor closes the network connection. + yourself once you don't use it anymore. The destructor + closes the network connection. - @sa wxInputStream + @see wxInputStream */ - wxInputStream * GetInputStream(const wxString& path); + wxInputStream* GetInputStream(const wxString& path); /** Tries to reestablish a previous opened connection (close and renegotiate diff --git a/interface/ptr_scpd.h b/interface/ptr_scpd.h index 13e6202ad5..24300e8dda 100644 --- a/interface/ptr_scpd.h +++ b/interface/ptr_scpd.h @@ -36,7 +36,7 @@ public: Creates the smart pointer with the given pointer or none if @NULL. On compilers that support it, this uses the explicit keyword. */ - explicit wxScopedPtr(type T = @NULL); + explicit wxScopedPtr(type T = NULL); /** Destructor frees the pointer help by this object if it is not @NULL. @@ -67,14 +67,14 @@ public: @NULL. After a call to this function the caller is responsible for deleting the pointer. */ - T * release(); + T* release(); /** - Deletes the currently held pointer and sets it to @e p or to @NULL if no + Deletes the currently held pointer and sets it to @a p or to @NULL if no arguments are specified. This function does check to make sure that the pointer you are assigning is not the same pointer that is already stored. */ - reset(T p = @NULL); + reset(T p = NULL); /** Swap the pointer inside the smart pointer with @e other. The pointer being @@ -105,7 +105,7 @@ public: Creates the smart pointer with the given pointer or none if @NULL. On compilers that support it, this uses the explicit keyword. */ - wxScopedArray(type T = @NULL); + wxScopedArray(type T = NULL); /** This operator gets the pointer stored in the smart pointer or returns @NULL if @@ -124,7 +124,7 @@ public: arguments are specified. This function does check to make sure that the pointer you are assigning is not the same pointer that is already stored. */ - reset(T p = @NULL); + reset(T p = NULL); /** Swap the pointer inside the smart pointer with 'ot'. The pointer being swapped @@ -153,17 +153,16 @@ class wxScopedTiedPtr { public: /** - Constructor creates a smart pointer initialized with @e ptr and stores - @e ptr in the location specified by @e ppTie which must not be + Constructor creates a smart pointer initialized with @a ptr and stores + @a ptr in the location specified by @a ppTie which must not be @NULL. */ - wxScopedTiedPtr(T ** ppTie, T * ptr); + wxScopedTiedPtr(T** ppTie, T* ptr); /** Destructor frees the pointer help by this object and restores the value stored at the tied location (as specified in the @ref ctor() constructor) to the old value. - Warning: this location may now contain an uninitialized value if it hadn't been initialized previously, in particular don't count on it magically being @NULL! @@ -191,7 +190,7 @@ public: /** Constructor. */ - wxScopedPtrT(T * ptr = @NULL); + wxScopedPtrT(T* ptr = NULL); /** Destructor. @@ -201,7 +200,7 @@ public: /** Returns pointer to object or @NULL. */ - T * get(); + T* get(); /** Conversion to a boolean expression (in a variant which is not @@ -221,7 +220,7 @@ public: Returns pointer to object. If the pointer is @NULL this method will cause an assert in debug mode. */ - T * operator-(); + T* operator-(); /** Releases the current pointer and returns it. @@ -234,10 +233,10 @@ public: Reset pointer to the value of @e ptr. The previous pointer will be deleted. */ - void reset(T * ptr = @NULL); + void reset(T* ptr = NULL); /** Swaps pointers. */ - void swap(wxScopedPtr & ot); + void swap(wxScopedPtr& ot); }; diff --git a/interface/ptr_shrd.h b/interface/ptr_shrd.h index d527784cff..139ceee10f 100644 --- a/interface/ptr_shrd.h +++ b/interface/ptr_shrd.h @@ -28,7 +28,7 @@ public: /** Constructors. */ - wxSharedPtrT(T* ptr = @NULL); + wxSharedPtrT(T* ptr = NULL); wxSharedPtrT(const wxSharedPtr& tocopy); //@} @@ -65,13 +65,13 @@ public: Assignment operator. Releases any previously held pointer and creates a reference to @e ptr. */ - wxSharedPtrT& operator operator=(T * ptr); + wxSharedPtrT& operator operator=(T* ptr); /** Reset pointer to @e ptr. If the reference count of the previously owned pointer was 1 it will be deleted. */ - void reset(T * ptr = @NULL); + void reset(T* ptr = NULL); /** Returns @true if this is the only pointer pointing to its object. diff --git a/interface/quantize.h b/interface/quantize.h index 200c91ff4a..afa4b21c1c 100644 --- a/interface/quantize.h +++ b/interface/quantize.h @@ -29,10 +29,8 @@ 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 variable). */ diff --git a/interface/radiobox.h b/interface/radiobox.h index 799165ff0b..dd57b38e78 100644 --- a/interface/radiobox.h +++ b/interface/radiobox.h @@ -26,7 +26,7 @@ @endStyleTable @beginEventTable - @event{EVT_RADIOBOX(id\, func)}: + @event{EVT_RADIOBOX(id, func)}: Process a wxEVT_COMMAND_RADIOBOX_SELECTED event, when a radiobutton is clicked. @endEventTable @@ -36,8 +36,7 @@ @appearance{radiobox.png} @seealso - @ref overview_eventhandlingoverview "Event handling overview", wxRadioButton, - wxCheckBox + @ref overview_eventhandlingoverview, wxRadioButton, wxCheckBox */ class wxRadioBox : public wxControlWithItems { @@ -47,43 +46,33 @@ public: Constructor, creating and showing a radiobox. @param parent - Parent window. Must not be @NULL. - + Parent window. Must not be @NULL. @param id - Window identifier. The value wxID_ANY indicates a default value. - + Window identifier. The value wxID_ANY indicates a default value. @param label - Label for the static box surrounding the radio buttons. - + 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 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 wxDefaultSize is specified then a default size + is chosen. @param n - Number of choices with which to initialize the radiobox. - + Number of choices with which to initialize the radiobox. @param choices - An array of choices with which to initialize the radiobox. - + 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 wxRA_SPECIFY_ROWS) + or columns (if style contains wxRA_SPECIFY_COLS) for a two-dimensional + radiobox. @param style - Window style. See wxRadioBox. - + Window style. See wxRadioBox. @param validator - Window validator. - + Window validator. @param name - Window name. + Window name. - @sa Create(), wxValidator + @see Create(), wxValidator */ wxRadioBox(); wxRadioBox(wxWindow* parent, wxWindowID id, @@ -91,7 +80,7 @@ public: const wxPoint& point = wxDefaultPosition, const wxSize& size = wxDefaultSize, int n = 0, - const wxString choices[] = @NULL, + const wxString choices[] = NULL, int majorDimension = 0, long style = wxRA_SPECIFY_COLS, const wxValidator& validator = wxDefaultValidator, @@ -122,7 +111,7 @@ public: const wxPoint& point = wxDefaultPosition, const wxSize& size = wxDefaultSize, int n = 0, - const wxString choices[] = @NULL, + const wxString choices[] = NULL, int majorDimension = 0, long style = wxRA_SPECIFY_COLS, const wxValidator& validator = wxDefaultValidator, @@ -143,15 +132,14 @@ public: Enables or disables an individual button in the radiobox. @param enable - @true to enable, @false to disable. - + @true to enable, @false to disable. @param n - The zero-based button to enable or disable. + The zero-based button to enable or disable. - @sa wxWindow::Enable + @see wxWindow::Enable */ - virtual bool Enable(bool enable = @true); - virtual bool Enable(unsigned int n, bool enable = @true); + virtual bool Enable(bool enable = true); + virtual bool Enable(unsigned int n, bool enable = true); //@} /** @@ -159,7 +147,7 @@ public: -1 if not found. @param string - The string to find. + The string to find. */ int FindString(const wxString& string); @@ -173,35 +161,35 @@ public: wxNOT_FOUND if no item is under the point. @param pt - Point in client coordinates. + Point in client coordinates. */ int GetItemFromPoint(const wxPoint pt); /** - Returns the helptext associated with the specified @e item if any or @c + Returns the helptext associated with the specified @a item if any or @c wxEmptyString. @param item - The zero-based item index. + The zero-based item index. - @sa SetItemHelpText() + @see SetItemHelpText() */ wxString GetItemHelpText(unsigned int item); /** - Returns the tooltip associated with the specified @e item if any or @NULL. + Returns the tooltip associated with the specified @a item if any or @NULL. - @sa SetItemToolTip(), wxWindow::GetToolTip + @see SetItemToolTip(), wxWindow::GetToolTip */ - wxToolTip * GetItemToolTip(unsigned int item); + wxToolTip* GetItemToolTip(unsigned int item); /** Returns the radiobox label. @param n - The zero-based button index. + The zero-based button index. - @sa SetLabel() + @see SetLabel() */ wxString GetLabel(); @@ -219,7 +207,7 @@ public: Returns the label for the button at the given position. @param n - The zero-based button position. + The zero-based button position. */ wxString GetString(unsigned int n); @@ -231,12 +219,11 @@ public: /** 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. @param n - The zero-based button position. + The zero-based button position. */ bool IsItemEnabled(unsigned int n); @@ -244,16 +231,14 @@ public: Returns @true if the item is currently shown or @false if it was hidden using @ref show() "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. @param n - The zero-based button position. + The zero-based button position. */ bool IsItemShown(unsigned int n); @@ -261,28 +246,25 @@ public: Sets the helptext for an item. Empty string erases any existing helptext. @param item - The zero-based item index. - + The zero-based item index. @param helptext - The help text to set for the item. + The help text to set for the item. - @sa GetItemHelpText() + @see GetItemHelpText() */ void SetItemHelpText(unsigned int item, const wxString& helptext); /** 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. @param item - Index of the item the tooltip will be shown for. - + Index of the item the tooltip will be shown for. @param text - Tooltip text for the item, the tooltip is removed if empty. + Tooltip text for the item, the tooltip is removed if empty. - @sa GetItemToolTip(), wxWindow::SetToolTip + @see GetItemToolTip(), wxWindow::SetToolTip */ void SetItemToolTip(unsigned int item, const wxString& text); @@ -290,10 +272,9 @@ public: Sets the radiobox label. @param label - The label to set. - + The label to set. @param n - The zero-based button index. + The zero-based button index. */ void SetLabel(const wxString& label); @@ -302,7 +283,7 @@ public: a wxEVT_COMMAND_RADIOBOX_SELECTED event to get emitted. @param n - The zero-based button position. + The zero-based button position. */ void SetSelection(int n); @@ -312,7 +293,7 @@ public: a wxEVT_COMMAND_RADIOBOX_SELECTED event to get emitted. @param string - The label of the button to select. + The label of the button to select. */ void SetStringSelection(const wxString& string); }; diff --git a/interface/radiobut.h b/interface/radiobut.h index 95ef21f39c..0fa6d4441c 100644 --- a/interface/radiobut.h +++ b/interface/radiobut.h @@ -32,7 +32,7 @@ @endStyleTable @beginEventTable - @event{EVT_RADIOBUTTON(id\, func)}: + @event{EVT_RADIOBUTTON(id, func)}: Process a wxEVT_COMMAND_RADIOBUTTON_SELECTED event, when the radiobutton is clicked. @endEventTable @@ -42,8 +42,7 @@ @appearance{radiobutton.png} @seealso - @ref overview_eventhandlingoverview "Event handling overview", wxRadioBox, - wxCheckBox + @ref overview_eventhandlingoverview, wxRadioBox, wxCheckBox */ class wxRadioButton : public wxControl { @@ -53,32 +52,25 @@ public: Constructor, creating and showing a radio button. @param parent - Parent window. Must not be @NULL. - + Parent window. Must not be @NULL. @param id - Window identifier. The value wxID_ANY indicates a default value. - + Window identifier. The value wxID_ANY indicates a default value. @param label - Label for the radio button. - + Label for the radio button. @param pos - Window position. If wxDefaultPosition is specified then a default position - is chosen. - + Window position. If 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 wxDefaultSize is specified then a default size + is chosen. @param style - Window style. See wxRadioButton. - + Window style. See wxRadioButton. @param validator - Window validator. - + Window validator. @param name - Window name. + Window name. - @sa Create(), wxValidator + @see Create(), wxValidator */ wxRadioButton(); wxRadioButton(wxWindow* parent, wxWindowID id, @@ -117,7 +109,7 @@ public: wxEVT_COMMAND_RADIOBUTTON_SELECTED event to get emitted. @param value - @true to select, @false to deselect. + @true to select, @false to deselect. */ void SetValue(const bool value); }; diff --git a/interface/recguard.h b/interface/recguard.h index 6aacefa3bd..e5c3a367c8 100644 --- a/interface/recguard.h +++ b/interface/recguard.h @@ -79,7 +79,6 @@ 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). */ @@ -90,7 +89,6 @@ public: 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(); diff --git a/interface/regex.h b/interface/regex.h index ae5d69eb26..be39e63ae7 100644 --- a/interface/regex.h +++ b/interface/regex.h @@ -65,9 +65,8 @@ public: //@{ /** - Returns the part of string corresponding to the match where @e index is + 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(). @@ -80,7 +79,6 @@ public: /** 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. */ @@ -96,19 +94,15 @@ public: /** Matches the precompiled regular expression against the string @e text, returns @true if matches and @false otherwise. - @e Flags may be combination of @c wxRE_NOTBOL and @c wxRE_NOTEOL. - 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 @e text cannot contain embedded nulls. - + 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. - May only be called after successful call to Compile(). */ bool Matches(const wxChar* text, int flags = 0); @@ -118,15 +112,13 @@ public: /** Replaces the current regular expression in the string pointed to by - @e text, with the text in @e replacement and return number of matches + @e 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 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. - - @e maxMatches may be used to limit the number of replacements made, setting + @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. */ @@ -137,7 +129,7 @@ public: Replace all occurrences: this is actually a synonym for Replace(). - @sa ReplaceFirst() + @see ReplaceFirst() */ int ReplaceAll(wxString* text, const wxString& replacement); diff --git a/interface/region.h b/interface/region.h index f0aa9ca40e..4483c9be5c 100644 --- a/interface/region.h +++ b/interface/region.h @@ -39,7 +39,7 @@ public: /** An alias for GetHeight. */ -#define wxCoord GetH() /* implementation is private */ + wxCoord GetH(); /** Returns the height value for the current region. @@ -54,7 +54,7 @@ public: /** An alias for GetWidth. */ -#define wxCoord GetW() /* implementation is private */ + wxCoord GetW(); /** Returns the width value for the current region. @@ -64,12 +64,12 @@ public: /** Returns the x value for the current region. */ -#define wxCoord GetX() /* implementation is private */ + wxCoord GetX(); /** Returns the y value for the current region. */ -#define wxCoord GetY() /* implementation is private */ + wxCoord GetY(); /** Returns @true if there are still some rectangles; otherwise returns @false. @@ -91,7 +91,6 @@ public: /** Returns @true if there are still some rectangles; otherwise returns @false. - You can use this to test the iterator object as if it were of type bool. */ operator bool(); @@ -155,7 +154,7 @@ public: region. @returns The return value is one of wxOutRegion, wxPartRegion and - wxInRegion. + wxInRegion. */ wxRegionContain Contains(long& x, long& y); wxRegionContain Contains(const wxPoint& pt); @@ -187,8 +186,8 @@ public: @returns @true if successful, @false otherwise. @remarks Creates the intersection of the two regions, that is, the parts - which are in both regions. The result is stored in - this region. + which are in both regions. The result is stored in this + region. */ bool Intersect(wxCoord x, wxCoord y, wxCoord width, wxCoord height); @@ -203,7 +202,7 @@ public: /** Returns @true if the region is equal to, i.e. covers the same area as, - another one. Note that if both this region and @e region are invalid, they + another one. Note that if both this region and @a region are invalid, they are considered to be equal. */ bool IsEqual(const wxRegion& region); @@ -214,7 +213,7 @@ public: directions. @returns @true if successful, @false otherwise (the region is unchanged - then). + then). */ bool Offset(wxCoord x, wxCoord y); bool Offset(const wxPoint& pt); @@ -227,8 +226,8 @@ public: @returns @true if successful, @false otherwise. @remarks This operation combines the parts of 'this' region that are not - part of the second region. The result is stored in - this region. + part of the second region. The result is stored in this + region. */ bool Subtract(const wxRect& rect); bool Subtract(const wxRegion& region); @@ -238,14 +237,14 @@ public: /** Finds the union of this region and the non-transparent pixels of a bitmap. Colour to be treated as transparent is specified in the - @e transColour argument, along with an + @a transColour argument, along with an optional colour tolerance value. @returns @true if successful, @false otherwise. @remarks This operation creates a region that combines all of this region - and the second region. The result is stored in this - region. + and the second region. The result is stored in this + region. */ bool Union(wxCoord x, wxCoord y, wxCoord width, wxCoord height); bool Union(const wxRect& rect); @@ -262,8 +261,8 @@ public: @returns @true if successful, @false otherwise. @remarks This operation creates a region that combines all of this region - and the second region, except for any overlapping - areas. The result is stored in this region. + and the second region, except for any overlapping + areas. The result is stored in this region. */ bool Xor(wxCoord x, wxCoord y, wxCoord width, wxCoord height); bool Xor(const wxRect& rect); diff --git a/interface/renderer.h b/interface/renderer.h index f491e0440c..c82bff47f0 100644 --- a/interface/renderer.h +++ b/interface/renderer.h @@ -24,14 +24,12 @@ class wxSplitterRenderParams public: /** const wxCoord border - The width of the border drawn by the splitter inside it, may be 0. */ /** const bool isHotSensitive - @true if the sash changes appearance when the mouse passes over it, @false otherwise. */ @@ -39,7 +37,6 @@ public: /** const wxCoord widthSash - The width of the splitter sash. */ }; @@ -81,10 +78,8 @@ public: The default constructor does the same thing as the other one except that it uses the @ref wxRendererNative::getgeneric "generic renderer" instead of the user-specified @e rendererNative. - In any case, this sets up the delegate renderer object to follow all calls to the specified real renderer. - Note that this object does not take ownership of (i.e. won't delete) @e rendererNative. */ @@ -162,20 +157,18 @@ public: /** Draw a check box (used by wxDataViewCtrl). - - @e flags may have the @c wxCONTROL_CHECKED, @c wxCONTROL_CURRENT or + @a flags may have the @c wxCONTROL_CHECKED, @c wxCONTROL_CURRENT or @c wxCONTROL_UNDETERMINED bit set. */ - void DrawCheckBox(wxWindow * win, wxDC& dc, const wxRect& rect, + void DrawCheckBox(wxWindow* win, wxDC& dc, const wxRect& rect, int flags); /** Draw a button like the one used by wxComboBox to show a drop down window. The usual appearance is a downwards pointing arrow. - - @e flags may have the @c wxCONTROL_PRESSED or @c wxCONTROL_CURRENT bit set. + @a flags may have the @c wxCONTROL_PRESSED or @c wxCONTROL_CURRENT bit set. */ - void DrawComboBoxDropButton(wxWindow * win, wxDC& dc, + void DrawComboBoxDropButton(wxWindow* win, wxDC& dc, const wxRect& rect, int flags); @@ -183,12 +176,11 @@ public: Draw a drop down arrow that is suitable for use outside a combo box. Arrow will have transparent background. - - @e rect is not entirely filled by the arrow. Instead, you should use bounding + @a rect is not entirely filled by the arrow. Instead, you should use bounding rectangle of a drop down button which arrow matches the size you need. - @e flags may have the @c wxCONTROL_PRESSED or @c wxCONTROL_CURRENT bit set. + @a flags may have the @c wxCONTROL_PRESSED or @c wxCONTROL_CURRENT bit set. */ - void DrawDropArrow(wxWindow * win, wxDC& dc, const wxRect& rect, + void DrawDropArrow(wxWindow* win, wxDC& dc, const wxRect& rect, int flags); /** @@ -202,9 +194,9 @@ public: /** Draw the header control button (used, for example, by wxListCtrl). Depending on platforms the - @e flags parameter may support the @c wxCONTROL_SELECTED + @a flags parameter may support the @c wxCONTROL_SELECTED @c wxCONTROL_DISABLED and @c wxCONTROL_CURRENT bits. - The @e sortArrow parameter can be one of + The @a sortArrow parameter can be one of @c wxHDR_SORT_ICON_NONE, @c wxHDR_SORT_ICON_UP, or @c wxHDR_SORT_ICON_DOWN. Additional values controlling the drawing of a text or bitmap label can be passed in @e params. The @@ -214,11 +206,11 @@ public: int DrawHeaderButton(wxWindow* win, wxDC& dc, const wxRect& rect, int flags = 0, wxHeaderSortIconType sortArrow = wxHDR_SORT_ICON_NONE, - wxHeaderButtonParams* params = @NULL); + wxHeaderButtonParams* params = NULL); /** Draw a selection rectangle underneath the text as used e.g. in a - wxListCtrl. The supported @e flags are + wxListCtrl. The supported @a flags are @c wxCONTROL_SELECTED for items which are selected (e.g. often a blue rectangle) and @c wxCONTROL_CURRENT for the item that has the focus (often a dotted line around the item's text). @c wxCONTROL_FOCUSED may @@ -232,11 +224,10 @@ public: /** Draw a blank push button that looks very similar to wxButton. - - @e flags may have the @c wxCONTROL_PRESSED, @c wxCONTROL_CURRENT or + @a flags may have the @c wxCONTROL_PRESSED, @c wxCONTROL_CURRENT or @c wxCONTROL_ISDEFAULT bit set. */ - void DrawPushButton(wxWindow * win, wxDC& dc, const wxRect& rect, + void DrawPushButton(wxWindow* win, wxDC& dc, const wxRect& rect, int flags); /** @@ -249,8 +240,8 @@ public: int flags = 0); /** - Draw a sash. The @e orient parameter defines whether the sash should be - vertical or horizontal and how the @e position should be interpreted. + Draw a sash. The @a orient parameter defines whether the sash should be + vertical or horizontal and how the @a position should be interpreted. */ void DrawSplitterSash(wxWindow* win, wxDC& dc, const wxSize& size, @@ -260,7 +251,7 @@ public: /** Draw the expanded/collapsed icon for a tree control item. To draw an expanded - button the @e flags parameter must contain @c wxCONTROL_EXPANDED bit. + button the @a flags parameter must contain @c wxCONTROL_EXPANDED bit. */ void DrawTreeItemButton(wxWindow* win, wxDC& dc, const wxRect& rect, @@ -269,7 +260,7 @@ public: /** Return the currently used renderer. */ -#define wxRendererNative Get() /* implementation is private */ + wxRendererNative Get(); /** Return the default (native) implementation for this platform -- this is also @@ -303,7 +294,6 @@ public: This function is used for version checking: Load() refuses to load any shared libraries implementing an older or incompatible version. - The implementation of this method is always the same in all renderers (simply construct wxRendererVersion using the @c wxRendererVersion::Current_XXX values), but it has to be in the derived, @@ -315,8 +305,7 @@ public: /** Load the renderer from the specified DLL, the returned pointer must be deleted by caller if not @NULL when it is not used any more. - - The @e name should be just the base name of the renderer and not the full + The @a name should be just the base name of the renderer and not the full name of the DLL file which is constructed differently (using wxDynamicLibrary::CanonicalizePluginName) on different systems. @@ -326,10 +315,9 @@ public: /** Set the renderer to use, passing @NULL reverts to using the default renderer (the global renderer must always exist). - Return the previous renderer used with Set() or @NULL if none. */ -#define wxRendererNative* Set(wxRendererNative* renderer) /* implementation is private */ + wxRendererNative* Set(wxRendererNative* renderer); }; @@ -359,7 +347,6 @@ public: /** Checks if the main program is compatible with the renderer having the version @e ver, returns @true if it is and @false otherwise. - This method is used by wxRendererNative::Load to determine whether a renderer can be used. @@ -368,14 +355,12 @@ public: /** const int age - The age component. */ /** const int version - The version component. */ }; diff --git a/interface/richtext/richtextbuffer.h b/interface/richtext/richtextbuffer.h index 3329ba9f46..a196108466 100644 --- a/interface/richtext/richtextbuffer.h +++ b/interface/richtext/richtextbuffer.h @@ -71,8 +71,7 @@ public: Begins collapsing undo/redo commands. Note that this may not work properly if combining commands that delete or insert content, changing ranges for subsequent actions. - - @e cmdName should be the name of the combined command that will appear + @a cmdName should be the name of the combined command that will appear next to Undo and Redo in the edit menu. */ bool BeginBatchUndo(const wxString& cmdName); @@ -103,10 +102,9 @@ public: bool BeginItalic(); /** - Begin using @e leftIndent for the left indent, and optionally @e leftSubIndent + Begin using @a leftIndent for the left indent, and optionally @a leftSubIndent for the sub-indent. Both are expressed in tenths of a millimetre. - The sub-indent is an offset from the left of the paragraph, and is used for all but the first line in a paragraph. A positive value will cause the first line to appear @@ -129,20 +127,16 @@ public: Begins using a specified list style. Optionally, you can also pass a level and a number. */ - bool BeginListStyle(const wxString& listStyle, int level=1, - int number=1); + bool BeginListStyle(const wxString& listStyle, int level = 1, + int number = 1); /** Begins a numbered bullet. This call will be needed for each item in the list, and the application should take care of incrementing the numbering. - - @e bulletNumber is a number, usually starting with 1. - - @e leftIndent and @e leftSubIndent are values in tenths of a millimetre. - - @e bulletStyle is a bitlist of the following values: - + @a bulletNumber is a number, usually starting with 1. + @a leftIndent and @a leftSubIndent are values in tenths of a millimetre. + @a bulletStyle is a bitlist of the following values: wxRichTextBuffer uses indentation to render a bulleted item. The left indent is the distance between @@ -246,11 +240,8 @@ public: /** Clears the list style from the given range, clearing list-related attributes and applying any named paragraph style associated with each paragraph. - - @e flags is a bit list of the following: - + @a flags is a bit list of the following: wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. - See also SetListStyle(), PromoteList(), NumberList(). */ bool ClearListStyle(const wxRichTextRange& range, @@ -396,7 +387,7 @@ public: /** Ends applying a URL. */ -#define bool EndURL() /* implementation is private */ + bool EndURL(); /** Ends using underline. @@ -447,13 +438,13 @@ public: const wxTextAttr GetDefaultStyle(); /** - Gets a wildcard incorporating all visible handlers. If @e types is present, + Gets a wildcard incorporating all visible handlers. If @a types is present, it will be filled with the file type corresponding to each filter. This can be used to determine the type to pass to @ref getextwildcard() LoadFile given a selected filter. */ - wxString GetExtWildcard(bool combine = @false, bool save = @false, - wxArrayInt* types = @NULL); + wxString GetExtWildcard(bool combine = false, bool save = false, + wxArrayInt* types = NULL); /** Returns the list of file handlers. @@ -468,7 +459,6 @@ public: /** Gets the attributes at the given position. - This function gets the combined style - that is, the style you see on the screen as a result of combining base style, paragraph style and character style attributes. To get @@ -483,13 +473,11 @@ public: Attributes which have different values within the specified range will not be included the style flags. - The function is used to get the attributes to display in the formatting dialog: the user can edit the attributes common to the selection, and optionally specify the values of further attributes to be applied uniformly. - To apply the edited attributes, you can use SetStyle() specifying the wxRICHTEXT_SETSTYLE_OPTIMIZE flag, which will only apply attributes that are different @@ -522,13 +510,11 @@ public: /** Gets the attributes at the given position. - This function gets the @e uncombined style - that is, the attributes associated with the paragraph or character content, and not necessarily the combined attributes you see on the screen. To get the combined attributes, use GetStyle(). - If you specify (any) paragraph attribute in @e style's flags, this function will fetch the paragraph attributes. Otherwise, it will return the character attributes. @@ -536,11 +522,10 @@ public: bool GetUncombinedStyle(long position, wxTextAttr& style); /** - Finds the text position for the given position, putting the position in @e + Finds the text position for the given position, putting the position in @a textPosition if - one is found. @e pt is in logical units (a zero y position is + one is found. @a pt is in logical units (a zero y position is at the beginning of the buffer). - The function returns one of the following values: */ int HitTest(wxDC& dc, const wxPoint& pt, long& textPosition); @@ -598,7 +583,7 @@ public: /** Marks the buffer as modified or unmodified. */ - void Modify(bool modify = @true); + void Modify(bool modify = true); //@{ /** @@ -606,15 +591,12 @@ public: attributes are set. Either the style definition or the name of the style definition (in the current sheet) can be passed. - - @e flags is a bit list of the following: - + @a flags is a bit list of the following: wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e startFrom, otherwise existing attributes are used. - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @e listLevel should be used + wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used as the level for all paragraphs, otherwise the current indentation will be used. - See also SetListStyle(), PromoteList(), ClearListStyle(). */ bool NumberList(const wxRichTextRange& range, @@ -636,20 +618,17 @@ public: //@{ /** - Promotes or demotes the paragraphs in the given range. A positive @e promoteBy + Promotes or demotes the paragraphs in the given range. A positive @a promoteBy produces a smaller indent, and a negative number produces a larger indent. Pass flags to determine how the attributes are set. Either the style definition or the name of the style definition (in the current sheet) can be passed. - - @e flags is a bit list of the following: - + @a flags is a bit list of the following: wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e startFrom, otherwise existing attributes are used. - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @e listLevel should be used + wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used as the level for all paragraphs, otherwise the current indentation will be used. - See also SetListStyle(), See also SetListStyle(), ClearListStyle(). */ bool PromoteList(int promoteBy, const wxRichTextRange& range, @@ -664,10 +643,10 @@ public: /** Removes an event handler from the buffer's list of handlers, deleting the - object if @e deleteHandler is @true. + object if @a deleteHandler is @true. */ bool RemoveEventHandler(wxEvtHandler* handler, - bool deleteHandler = @false); + bool deleteHandler = false); /** Removes a handler. @@ -701,7 +680,6 @@ public: Sets the default style, affecting the style currently being applied (for example, setting the default style to bold will cause subsequently inserted text to be bold). - This is not cumulative - setting the default style will replace the previous default style. */ @@ -713,15 +691,12 @@ public: the attributes are set. Either the style definition or the name of the style definition (in the current sheet) can be passed. - - @e flags is a bit list of the following: - + @a flags is a bit list of the following: wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e startFrom, otherwise existing attributes are used. - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @e listLevel should be used + wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used as the level for all paragraphs, otherwise the current indentation will be used. - See also NumberList(), PromoteList(), ClearListStyle(). */ bool SetListStyle(const wxRichTextRange& range, @@ -737,7 +712,7 @@ public: //@} /** - Sets @e renderer as the object to be used to render certain aspects of the + Sets @a renderer as the object to be used to render certain aspects of the content, such as bullets. You can override default rendering by deriving a new class from wxRichTextRenderer or wxRichTextStdRenderer, @@ -749,15 +724,12 @@ public: /** Sets the attributes for the given range. Pass flags to determine how the attributes are set. - The end point of range is specified as the last character position of the span of text. So, for example, to set the style for a character at position 5, use the range (5,5). This differs from the wxRichTextCtrl API, where you would specify (5,6). - - @e flags may contain a bit list of the following values: - + @a flags may contain a bit list of the following values: wxRICHTEXT_SETSTYLE_NONE: no style flag. wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this operation should be undoable. @@ -837,12 +809,12 @@ public: bool CanSave(); /** - Override to load content from @e stream into @e buffer. + Override to load content from @a stream into @e buffer. */ bool DoLoadFile(wxRichTextBuffer* buffer, wxInputStream& stream); /** - Override to save content to @e stream from @e buffer. + Override to save content to @a stream from @e buffer. */ bool DoSaveFile(wxRichTextBuffer* buffer, wxOutputStream& stream); @@ -912,7 +884,6 @@ public: Sets flags that change the behaviour of loading or saving. See the documentation for each handler class to see what flags are relevant for each handler. - You call this function directly if you are using a file handler explicitly (without going through the text control or buffer LoadFile/SaveFile API). Or, you can @@ -1041,22 +1012,22 @@ public: wxRichTextRange ToInternal(); /** - Adds @e range to this range. + Adds @a range to this range. */ wxRichTextRange operator+(const wxRichTextRange& range); /** - Subtracts @e range from this range. + Subtracts @a range from this range. */ wxRichTextRange operator-(const wxRichTextRange& range); /** - Assigns @e range to this range. + Assigns @a range to this range. */ void operator=(const wxRichTextRange& range); /** - Returns @true if @e range is the same as this range. + Returns @true if @a range is the same as this range. */ bool operator==(const wxRichTextRange& range); }; diff --git a/interface/richtext/richtextctrl.h b/interface/richtext/richtextctrl.h index 0231107f28..0fa881bdaa 100644 --- a/interface/richtext/richtextctrl.h +++ b/interface/richtext/richtextctrl.h @@ -23,7 +23,7 @@ public: Constructors. */ wxRichTextEvent(const wxRichTextEvent& event); - wxRichTextEvent(wxEventType commandType = wxEVT_@NULL, + wxRichTextEvent(wxEventType commandType = wxEVT_NULL, int winid = 0); //@} @@ -160,7 +160,6 @@ public: /** Applies the given alignment to the selection (undoable). - For alignment values, see wxTextAttr. */ bool ApplyAlignmentToSelection(wxTextAttrAlignment alignment); @@ -183,13 +182,12 @@ public: /** Applies the style sheet to the buffer, matching paragraph styles in the sheet against named styles - in the buffer. This might be useful if the styles have changed. If @e sheet is + in the buffer. This might be useful if the styles have changed. If @a sheet is @NULL, the sheet set with SetStyleSheet is used. - Currently this applies paragraph styles only. */ - bool ApplyStyleSheet(wxRichTextStyleSheet* sheet = @NULL); + bool ApplyStyleSheet(wxRichTextStyleSheet* sheet = NULL); /** Applies underline to the selection (undoable). @@ -203,7 +201,6 @@ public: /** Begins using alignment - For alignment values, see wxTextAttr. */ bool BeginAlignment(wxTextAttrAlignment alignment); @@ -240,7 +237,6 @@ public: /** Begins applying a left indent and subindent in tenths of a millimetre. - The sub-indent is an offset from the left of the paragraph, and is used for all but the first line in a paragraph. A positive value will cause the first line to appear @@ -248,7 +244,6 @@ public: of the subsequent lines, and a negative value will cause the first line to be indented relative to the subsequent lines. - wxRichTextBuffer uses indentation to render a bulleted item. The left indent is the distance between the margin and the bullet. The content of the paragraph, including the first @@ -271,20 +266,16 @@ public: Begins using a specified list style. Optionally, you can also pass a level and a number. */ - bool BeginListStyle(const wxString& listStyle, int level=1, - int number=1); + bool BeginListStyle(const wxString& listStyle, int level = 1, + int number = 1); /** Begins a numbered bullet. This call will be needed for each item in the list, and the application should take care of incrementing the numbering. - - @e bulletNumber is a number, usually starting with 1. - - @e leftIndent and @e leftSubIndent are values in tenths of a millimetre. - - @e bulletStyle is a bitlist of the following values: - + @a bulletNumber is a number, usually starting with 1. + @a leftIndent and @a leftSubIndent are values in tenths of a millimetre. + @a bulletStyle is a bitlist of the following values: wxRichTextBuffer uses indentation to render a bulleted item. The left indent is the distance between @@ -392,11 +383,8 @@ public: /** Clears the list style from the given range, clearing list-related attributes and applying any named paragraph style associated with each paragraph. - - @e flags is a bit list of the following: - + @a flags is a bit list of the following: wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. - See also SetListStyle(), PromoteList(), NumberList(). */ bool ClearListStyle(const wxRichTextRange& range, @@ -430,7 +418,7 @@ public: Copies the selected content (if any) to the clipboard and deletes the selection. This is undoable. */ -#define void Cut() /* implementation is private */ + void Cut(); /** Deletes the content within the given range. @@ -442,7 +430,7 @@ public: Returns the new caret position in @e newPos, or leaves it if there was no action. This is undoable. */ - bool DeleteSelectedContent(long* newPos = @NULL); + bool DeleteSelectedContent(long* newPos = NULL); /** Deletes the content in the selection, if any. This is undoable. @@ -558,7 +546,7 @@ public: /** Ends applying a URL. */ -#define bool EndURL() /* implementation is private */ + bool EndURL(); /** End applying underlining. @@ -683,7 +671,6 @@ public: /** Gets the text for the given range. - The end point of range is specified as the last character position of the span of text, plus one. */ @@ -691,11 +678,9 @@ public: /** Returns the range of the current selection. - The end point of range is specified as the last character position of the span of text, plus one. - - If the return values @e from and @e to are the same, there is no selection. + If the return values @a from and @a to are the same, there is no selection. */ void GetSelection(long* from, long* to); @@ -711,7 +696,6 @@ public: /** Gets the attributes at the given position. - This function gets the combined style - that is, the style you see on the screen as a result of combining base style, paragraph style and character style attributes. To get @@ -737,13 +721,11 @@ public: /** Gets the attributes at the given position. - This function gets the @e uncombined style - that is, the attributes associated with the paragraph or character content, and not necessarily the combined attributes you see on the screen. To get the combined attributes, use GetStyle(). - If you specify (any) paragraph attribute in @e style's flags, this function will fetch the paragraph attributes. Otherwise, it will return the character attributes. @@ -767,7 +749,7 @@ public: /** Test if this whole range has character attributes of the specified kind. If any of the attributes are different within the range, the test fails. You - can use this to implement, for example, bold button updating. @e style must have + can use this to implement, for example, bold button updating. @a style must have flags indicating which attributes are of interest. */ bool HasCharacterAttributes(const wxRichTextRange& range, @@ -776,7 +758,7 @@ public: /** Test if this whole range has paragraph attributes of the specified kind. If any of the attributes are different within the range, the test fails. You - can use this to implement, for example, centering button updating. @e style + can use this to implement, for example, centering button updating. @a style must have flags indicating which attributes are of interest. */ @@ -791,8 +773,7 @@ public: //@{ /** Finds the character at the given position in pixels. - - @e pt is in device coords (not adjusted for the client area origin nor for + @a pt is in device coords (not adjusted for the client area origin nor for scrolling). */ wxTextCtrlHitTestResult HitTest(const wxPoint& pt, long* pos); @@ -816,9 +797,9 @@ public: the caret, and therefore the UI needs to reflect the default style and not the style at the caret. - Below is an example of code that uses this function to determine whether the UI should show that the current style is bold. + See also SetAndShowDefaultStyle(). */ bool IsDefaultStyleShowing(); @@ -885,7 +866,7 @@ public: setting the caret position. This function should not normally be required by the application. */ - bool LayoutContent(bool onlyVisibleRect = @false); + bool LayoutContent(bool onlyVisibleRect = false); /** Inserts a line break at the current insertion point. A line break forces @@ -900,7 +881,6 @@ public: Loads content into the control's buffer using the given type. If the specified type is wxRICHTEXT_TYPE_ANY, the type is deduced from the filename extension. - This function looks for a suitable wxRichTextFileHandler object. */ bool LoadFile(const wxString& file, @@ -914,7 +894,7 @@ public: /** Move the caret to the given character position. */ - bool MoveCaret(long pos, bool showAtLineStart = @false); + bool MoveCaret(long pos, bool showAtLineStart = false); /** Move the caret one visual step forward: this may mean setting a flag @@ -991,15 +971,12 @@ public: attributes are set. Either the style definition or the name of the style definition (in the current sheet) can be passed. - - @e flags is a bit list of the following: - + @a flags is a bit list of the following: wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e startFrom, otherwise existing attributes are used. - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @e listLevel should be used + wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used as the level for all paragraphs, otherwise the current indentation will be used. - See also SetListStyle(), PromoteList(), ClearListStyle(). */ bool NumberList(const wxRichTextRange& range, @@ -1128,20 +1105,17 @@ public: //@{ /** - Promotes or demotes the paragraphs in the given range. A positive @e promoteBy + Promotes or demotes the paragraphs in the given range. A positive @a promoteBy produces a smaller indent, and a negative number produces a larger indent. Pass flags to determine how the attributes are set. Either the style definition or the name of the style definition (in the current sheet) can be passed. - - @e flags is a bit list of the following: - + @a flags is a bit list of the following: wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e startFrom, otherwise existing attributes are used. - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @e listLevel should be used + wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used as the level for all paragraphs, otherwise the current indentation will be used. - See also SetListStyle(), See also SetListStyle(), ClearListStyle(). */ bool PromoteList(int promoteBy, const wxRichTextRange& range, @@ -1173,14 +1147,13 @@ public: /** Saves the buffer content using the given type. If the specified type is wxRICHTEXT_TYPE_ANY, the type is deduced from the filename extension. - This function looks for a suitable wxRichTextFileHandler object. */ bool SaveFile(const wxString& file = wxEmptyString, int type = wxRICHTEXT_TYPE_ANY); /** - Scrolls @e position into view. This function takes a caret position. + Scrolls @a position into view. This function takes a caret position. */ bool ScrollIntoView(long position, int keyCode); @@ -1195,10 +1168,9 @@ public: void SelectNone(); /** - Sets @e attr as the default style and tells the control that the UI should + Sets @a attr as the default style and tells the control that the UI should reflect this attribute until the user moves the caret. - See also IsDefaultStyleShowing(). */ void SetAndShowDefaultStyle(const wxTextAttr& attr); @@ -1216,7 +1188,7 @@ public: A value of -1 means the caret is at the start of the buffer. */ void SetCaretPosition(long position, - bool showAtLineStart = @false); + bool showAtLineStart = false); /** Sets the current default style, which can be used to change how subsequently @@ -1275,15 +1247,12 @@ public: the attributes are set. Either the style definition or the name of the style definition (in the current sheet) can be passed. - - @e flags is a bit list of the following: - + @a flags is a bit list of the following: wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e startFrom, otherwise existing attributes are used. - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @e listLevel should be used + wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used as the level for all paragraphs, otherwise the current indentation will be used. - See also NumberList(), PromoteList(), ClearListStyle(). */ bool SetListStyle(const wxRichTextRange& range, @@ -1300,7 +1269,6 @@ public: /** Sets the selection to the given range. - The end point of range is specified as the last character position of the span of text, plus one. So, for example, to set the selection for a character at position 5, use the @@ -1310,7 +1278,6 @@ public: /** Sets the selection to the given range. - The end point of range is specified as the last character position of the span of text, plus one. So, for example, to set the selection for a character at position 5, use the @@ -1321,7 +1288,6 @@ public: //@{ /** Sets the attributes for the given range. - The end point of range is specified as the last character position of the span of text, plus one. So, for example, to set the style for a character at position 5, use the range @@ -1336,14 +1302,11 @@ public: /** Sets the attributes for the given range, passing flags to determine how the attributes are set. - The end point of range is specified as the last character position of the span of text, plus one. So, for example, to set the style for a character at position 5, use the range (5,6). - - @e flags may contain a bit list of the following values: - + @a flags may contain a bit list of the following values: wxRICHTEXT_SETSTYLE_NONE: no style flag. wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this operation should be undoable. @@ -1385,7 +1348,7 @@ public: /** A helper function setting up scrollbars, for example after a resize. */ - void SetupScrollbars(bool atTop = @false); + void SetupScrollbars(bool atTop = false); /** Scrolls the buffer so that the given position is in view. diff --git a/interface/richtext/richtextformatdlg.h b/interface/richtext/richtextformatdlg.h index 967e12d178..1ca12a751d 100644 --- a/interface/richtext/richtextformatdlg.h +++ b/interface/richtext/richtextformatdlg.h @@ -121,25 +121,19 @@ public: Constructors. @param flags - The pages to show. - + The pages to show. @param parent - The dialog's parent. - + The dialog's parent. @param id - The dialog's identifier. - + The dialog's identifier. @param title - The dialog's caption. - + The dialog's caption. @param pos - The dialog's position. - + The dialog's position. @param size - The dialog's size. - + The dialog's size. @param style - The dialog's window style. + The dialog's window style. */ wxRichTextFormattingDialog(long flags, wxWindow* parent); const wxPoint& pos = wxDefaultPosition, const wxSize& sz = wxDefaultSize, long style = wxDEFAULT_DIALOG_STYLE) @@ -238,17 +232,17 @@ public: void SetImageList(wxImageList* imageList); /** - Sets the attributes and optionally updates the display, if @e update is @true. + Sets the attributes and optionally updates the display, if @a update is @true. */ - bool SetStyle(const wxTextAttr& style, bool update = @true); + bool SetStyle(const wxTextAttr& style, bool update = true); /** - Sets the style definition and optionally update the display, if @e update is @c + Sets the style definition and optionally update the display, if @a update is @c @true. */ bool SetStyleDefinition(const wxRichTextStyleDefinition& styleDef, wxRichTextStyleSheet* sheet, - bool update = @true); + bool update = true); /** Updates the display. diff --git a/interface/richtext/richtexthtml.h b/interface/richtext/richtexthtml.h index cd7ee0185b..7817e3708b 100644 --- a/interface/richtext/richtexthtml.h +++ b/interface/richtext/richtexthtml.h @@ -40,7 +40,6 @@ class wxRichTextHTMLHandler : public wxRichTextFileHandler public: /** , @b const wxString&@e ext = wxT("html"), @b int@e type = wxRICHTEXT_TYPE_HTML) - Constructor. */ wxRichTextHTMLHandler(); @@ -94,7 +93,6 @@ public: There should be 7 elements, one for each HTML font size, each element specifying the maximum point size for that HTML font size. - For example: */ void SetFontSizeMapping(const wxArrayInt& fontSizeMapping); diff --git a/interface/richtext/richtextprint.h b/interface/richtext/richtextprint.h index 35dd8a3092..47ccee35b8 100644 --- a/interface/richtext/richtextprint.h +++ b/interface/richtext/richtextprint.h @@ -172,7 +172,6 @@ class wxRichTextPrintout : public wxPrintout public: /** ) - Constructor. */ wxRichTextPrintout(); @@ -250,7 +249,6 @@ class wxRichTextPrinting : public wxObject public: /** , @b wxWindow*@e parentWindow = @NULL) - Constructor. Optionally pass a title to be used in the preview frame and printing wait dialog, and also a parent window for these windows. @@ -314,7 +312,7 @@ public: bool PreviewBuffer(const wxRichTextBuffer& buffer); /** - Shows a preview window for the given file. @e richTextFile can be a text file + Shows a preview window for the given file. @a richTextFile can be a text file or XML file, or other file depending on the available file handlers. */ @@ -326,7 +324,7 @@ public: bool PrintBuffer(const wxRichTextBuffer& buffer); /** - Prints the given file. @e richTextFile can be a text file or XML file, or other + Prints the given file. @a richTextFile can be a text file or XML file, or other file depending on the available file handlers. */ diff --git a/interface/richtext/richtextstyledlg.h b/interface/richtext/richtextstyledlg.h index 6d059e21f0..ed395c6024 100644 --- a/interface/richtext/richtextstyledlg.h +++ b/interface/richtext/richtextstyledlg.h @@ -25,90 +25,71 @@ public: //@{ /** Constructors. - - To create a dialog, pass a bitlist of @e flags (see below), a style sheet, a + To create a dialog, pass a bitlist of @a flags (see below), a style sheet, a text control to apply a selected style to (or @NULL), followed by the usual window parameters. - To specify the operations available to the user, pass a combination of these values to @e flags: - @b wxRICHTEXT_ORGANISER_DELETE_STYLES - Provides a button for deleting styles. @b wxRICHTEXT_ORGANISER_CREATE_STYLES - Provides buttons for creating styles. @b wxRICHTEXT_ORGANISER_APPLY_STYLES - Provides a button for applying the currently selected style to the selection. @b wxRICHTEXT_ORGANISER_EDIT_STYLES - Provides a button for editing styles. @b wxRICHTEXT_ORGANISER_RENAME_STYLES - Provides a button for renaming styles. @b wxRICHTEXT_ORGANISER_OK_CANCEL - Provides OK and Cancel buttons. @b wxRICHTEXT_ORGANISER_RENUMBER - Provides a checkbox for specifying that the selection should be renumbered. The following flags determine what will be displayed in the style list: - @b wxRICHTEXT_ORGANISER_SHOW_CHARACTER - Displays character styles only. @b wxRICHTEXT_ORGANISER_SHOW_PARAGRAPH - Displays paragraph styles only. @b wxRICHTEXT_ORGANISER_SHOW_LIST - Displays list styles only. @b wxRICHTEXT_ORGANISER_SHOW_ALL - Displays all styles. The following symbols define commonly-used combinations of flags: - @b wxRICHTEXT_ORGANISER_ORGANISE - Enable all style editing operations so the dialog behaves as a style organiser. @b wxRICHTEXT_ORGANISER_BROWSE - Show a list of all styles and their previews, but only allow application of a style or cancellation of the dialog. This makes the dialog behave as a style browser. @b wxRICHTEXT_ORGANISER_BROWSE_NUMBERING - Enables only list style browsing, plus a control to specify renumbering. This allows the dialog to be used for applying list styles to the selection. */ @@ -125,12 +106,11 @@ public: Applies the selected style to selection in the given control or the control passed to the constructor. */ - bool ApplyStyle(wxRichTextCtrl* ctrl = @NULL); + bool ApplyStyle(wxRichTextCtrl* ctrl = NULL); /** , @b const wxPoint&@e pos = wxDefaultPosition, @b const wxSize&@e size = wxDefaultSize, @b long@e style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxSYSTEM_MENU|wxCLOSE_BOX) - Creates the dialog. See */ bool Create(int flags, wxRichTextStyleSheet* sheet, diff --git a/interface/richtext/richtextstyles.h b/interface/richtext/richtextstyles.h index 22649713d4..93d769616d 100644 --- a/interface/richtext/richtextstyles.h +++ b/interface/richtext/richtextstyles.h @@ -305,7 +305,7 @@ public: void OnSelect(wxCommandEvent& event); /** - If @e applyOnSelection is @true, clicking on a style name in the list will + If @a applyOnSelection is @true, clicking on a style name in the list will immediately apply the style to the associated rich text control. */ @@ -461,45 +461,44 @@ public: /** This function combines the given paragraph style with the list style's base attributes and level style matching the given indent, returning the combined attributes. - If @e styleSheet is specified, the base style for this definition will also be + If @a styleSheet is specified, the base style for this definition will also be included in the result. */ wxTextAttr CombineWithParagraphStyle(int indent, const wxTextAttr& paraStyle, - wxRichTextStyleSheet* styleSheet = @NULL); + wxRichTextStyleSheet* styleSheet = NULL); /** This function finds the level (from 0 to 9) whose indentation attribute mostly - closely matches @e indent (expressed in tenths of a millimetre). + closely matches @a indent (expressed in tenths of a millimetre). */ int FindLevelForIndent(int indent); /** This function combines the list style's base attributes and the level style matching the given indent, returning the combined attributes. - If @e styleSheet is specified, the base style for this definition will also be + If @a styleSheet is specified, the base style for this definition will also be included in the result. */ wxTextAttr GetCombinedStyle(int indent, - wxRichTextStyleSheet* styleSheet = @NULL); + wxRichTextStyleSheet* styleSheet = NULL); /** This function combines the list style's base attributes and the style for the specified level, returning the combined attributes. - If @e styleSheet is specified, the base style for this definition will also be + If @a styleSheet is specified, the base style for this definition will also be included in the result. */ wxTextAttr GetCombinedStyleLevel(int level, - wxRichTextStyleSheet* styleSheet = @NULL); + wxRichTextStyleSheet* styleSheet = NULL); /** - Returns the style for the given level. @e level is a number between 0 and 9. + Returns the style for the given level. @a level is a number between 0 and 9. */ const wxTextAttr* GetLevelAttributes(int level); /** Returns the number of levels. This is hard-wired to 10. - Returns the style for the given level. @e level is a number between 0 and 9. */ int GetLevelCount(); @@ -511,8 +510,7 @@ public: //@{ /** - Sets the style for the given level. @e level is a number between 0 and 9. - + Sets the style for the given level. @a level is a number between 0 and 9. The first and most flexible form uses a wxTextAttr object, while the second form is for convenient setting of the most commonly-used attributes. */ @@ -641,25 +639,25 @@ public: Removes a character style. */ bool RemoveCharacterStyle(wxRichTextStyleDefinition* def, - bool deleteStyle = @false); + bool deleteStyle = false); /** Removes a list style. */ bool RemoveListStyle(wxRichTextStyleDefinition* def, - bool deleteStyle = @false); + bool deleteStyle = false); /** Removes a paragraph style. */ bool RemoveParagraphStyle(wxRichTextStyleDefinition* def, - bool deleteStyle = @false); + bool deleteStyle = false); /** Removes a style. */ bool RemoveStyle(wxRichTextStyleDefinition* def, - bool deleteStyle = @false); + bool deleteStyle = false); /** Sets the style sheet's description. diff --git a/interface/richtext/richtextsymboldlg.h b/interface/richtext/richtextsymboldlg.h index 871aa647ba..a0de9df2a6 100644 --- a/interface/richtext/richtextsymboldlg.h +++ b/interface/richtext/richtextsymboldlg.h @@ -83,34 +83,26 @@ public: Constructors. @param symbol - The initial symbol to show. Specify a single character in a string, or an empty - string. - + The initial symbol to show. Specify a single character in a string, or an + empty string. @param initialFont - The initial font to be displayed in the font list. If empty, the item normal - text will be selected. - + The initial font to be displayed in the font list. If empty, the item + normal text will be selected. @param normalTextFont - The font the dialog will use to display the symbols if the initial font is + The font the dialog will use to display the symbols if the initial font is empty. - @param parent - The dialog's parent. - + The dialog's parent. @param id - The dialog's identifier. - + The dialog's identifier. @param title - The dialog's caption. - + The dialog's caption. @param pos - The dialog's position. - + The dialog's position. @param size - The dialog's size. - + The dialog's size. @param style - The dialog's window style. + The dialog's window style. */ wxSymbolPickerDialog(const wxString& symbol, const wxString& initialFont, @@ -124,7 +116,6 @@ public: /** , @b const wxPoint&@e pos = wxDefaultPosition, @b const wxSize&@e size = wxDefaultSize, @b long@e style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxCLOSE_BOX) - Creation: see @ref wxsymbolpickerdialog() "the constructor" for details about the parameters. */ diff --git a/interface/richtext/richtextxml.h b/interface/richtext/richtextxml.h index 8f19093f70..e429030d7f 100644 --- a/interface/richtext/richtextxml.h +++ b/interface/richtext/richtextxml.h @@ -24,7 +24,6 @@ class wxRichTextXMLHandler : public wxRichTextFileHandler public: /** , @b const wxString&@e ext = wxT("xml"), @b int@e type = wxRICHTEXT_TYPE_XML) - Constructor. */ wxRichTextXMLHandler(); @@ -42,7 +41,7 @@ public: /** Creates XML code for a given character or paragraph style. */ - wxString CreateStyle(const wxTextAttr& attr, bool isPara = @false); + wxString CreateStyle(const wxTextAttr& attr, bool isPara = false); /** Loads buffer context from the given stream. @@ -81,14 +80,14 @@ public: Helper function: gets style parameters from the given XML node. */ bool GetStyle(wxTextAttr& attr, wxXmlNode* node, - bool isPara = @false); + bool isPara = false); /** Helper function: gets text from the node. */ wxString GetText(wxXmlNode* node, const wxString& param = wxEmptyString, - bool translate = @false); + bool translate = false); /** Helper function: returns @true if the node has the given parameter. diff --git a/interface/sashwin.h b/interface/sashwin.h index b567d0688b..87fc7604e1 100644 --- a/interface/sashwin.h +++ b/interface/sashwin.h @@ -29,10 +29,10 @@ @endStyleTable @beginEventTable - @event{EVT_SASH_DRAGGED(id\, func)}: + @event{EVT_SASH_DRAGGED(id, func)}: Process a wxEVT_SASH_DRAGGED event, when the user has finished dragging a sash. - @event{EVT_SASH_DRAGGED_RANGE(id1\, id2\, func)}: + @event{EVT_SASH_DRAGGED_RANGE(id1, id2, func)}: Process a wxEVT_SASH_DRAGGED_RANGE event, when the user has finished dragging a sash. The event handler is called when windows with ids in the given range have their sashes dragged. @@ -42,8 +42,7 @@ @category{miscwnd} @seealso - wxSashEvent, wxSashLayoutWindow, @ref overview_eventhandlingoverview "Event - handling overview" + wxSashEvent, wxSashLayoutWindow, @ref overview_eventhandlingoverview */ class wxSashWindow : public wxWindow { @@ -54,33 +53,28 @@ public: non-control window. @param parent - Pointer to a parent window. - + Pointer to a parent window. @param id - Window identifier. If -1, will automatically create an identifier. - + Window identifier. If -1, will automatically create an identifier. @param pos - Window position. wxDefaultPosition is (-1, -1) which indicates that + Window position. wxDefaultPosition is (-1, -1) which indicates that wxSashWindows - should generate a default position for the window. If using the wxSashWindow - class directly, supply - an actual position. - + should generate a default position for the window. If using the + wxSashWindow class directly, supply + an actual position. @param size - Window size. wxDefaultSize is (-1, -1) which indicates that wxSashWindows - should generate a default size for the window. - + Window size. wxDefaultSize is (-1, -1) which indicates that wxSashWindows + should generate a default size for the window. @param style - Window style. For window styles, please see wxSashWindow. - + Window style. For window styles, please see wxSashWindow. @param name - Window name. + Window name. */ wxSashWindow(); wxSashWindow(wxWindow* parent, wxWindowID id, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, - long style = wxCLIP_CHILDREN | wxSW_3D, + long style = wxCLIP_CHILDREN | wxSW_3D, const wxString& name = "sashWindow"); //@} @@ -113,9 +107,9 @@ public: Returns @true if a sash is visible on the given edge, @false otherwise. @param edge - Edge. One of wxSASH_TOP, wxSASH_RIGHT, wxSASH_BOTTOM, wxSASH_LEFT. + Edge. One of wxSASH_TOP, wxSASH_RIGHT, wxSASH_BOTTOM, wxSASH_LEFT. - @sa SetSashVisible() + @see SetSashVisible() */ bool GetSashVisible(wxSashEdgePosition edge); @@ -124,9 +118,9 @@ public: This function is obsolete since the sash border property is unused. @param edge - Edge. One of wxSASH_TOP, wxSASH_RIGHT, wxSASH_BOTTOM, wxSASH_LEFT. + Edge. One of wxSASH_TOP, wxSASH_RIGHT, wxSASH_BOTTOM, wxSASH_LEFT. - @sa SetSashBorder() + @see SetSashBorder() */ bool HasBorder(wxSashEdgePosition edge); @@ -155,10 +149,9 @@ public: This function is obsolete since the sash border property is unused. @param edge - Edge to change. One of wxSASH_TOP, wxSASH_RIGHT, wxSASH_BOTTOM, wxSASH_LEFT. - + Edge to change. One of wxSASH_TOP, wxSASH_RIGHT, wxSASH_BOTTOM, wxSASH_LEFT. @param hasBorder - @true to give the sash a border visible, @false to remove it. + @true to give the sash a border visible, @false to remove it. */ void SetSashBorder(wxSashEdgePosition edge, bool hasBorder); @@ -166,12 +159,11 @@ public: Call this function to make a sash visible or invisible on a particular edge. @param edge - Edge to change. One of wxSASH_TOP, wxSASH_RIGHT, wxSASH_BOTTOM, wxSASH_LEFT. - + Edge to change. One of wxSASH_TOP, wxSASH_RIGHT, wxSASH_BOTTOM, wxSASH_LEFT. @param visible - @true to make the sash visible, @false to make it invisible. + @true to make the sash visible, @false to make it invisible. - @sa GetSashVisible() + @see GetSashVisible() */ void SetSashVisible(wxSashEdgePosition edge, bool visible); }; @@ -188,7 +180,7 @@ public: @category{FIXME} @seealso - wxSashWindow, @ref overview_eventhandlingoverview "Event handling overview" + wxSashWindow, @ref overview_eventhandlingoverview */ class wxSashEvent : public wxCommandEvent { diff --git a/interface/sckipc.h b/interface/sckipc.h index 6bb30a3828..ffb819cc57 100644 --- a/interface/sckipc.h +++ b/interface/sckipc.h @@ -47,7 +47,7 @@ public: Under Unix, when a server is created the OnAcceptConnection message is always sent for standard input and output. */ - virtual wxConnectionBase * OnAcceptConnection(const wxString& topic); + virtual wxConnectionBase* OnAcceptConnection(const wxString& topic); }; @@ -92,22 +92,21 @@ public: the OnMakeConnection() member to return your own derived connection object. */ - wxConnectionBase * MakeConnection(const wxString& host, - const wxString& service, - const wxString& topic); + wxConnectionBase* MakeConnection(const wxString& host, + const wxString& service, + const wxString& topic); /** The type of wxTCPConnection returned from a MakeConnection() call can be altered by deriving the @b OnMakeConnection member to return your own derived connection object. By default, a wxTCPConnection object is returned. - The advantage of deriving your own connection class is that it will enable you to intercept messages initiated by the server, such as wxTCPConnection::OnAdvise. You may also want to store application-specific data in instances of the new class. */ - wxConnectionBase * OnMakeConnection(); + wxConnectionBase* OnMakeConnection(); /** Returns @true if this is a valid host name, @false otherwise. @@ -247,7 +246,7 @@ public: */ virtual const void* OnRequest(const wxString& topic, const wxString& item, - size_t * size, + size_t* size, wxIPCFormat format); /** @@ -287,7 +286,7 @@ public: character string (actually a pointer to the connection's buffer) if successful, @NULL otherwise. */ - const void* Request(const wxString& item, size_t * size, + const void* Request(const wxString& item, size_t* size, wxIPCFormat format = wxIPC_TEXT); /** diff --git a/interface/scopeguard.h b/interface/scopeguard.h index 0d1a8b501b..345c171447 100644 --- a/interface/scopeguard.h +++ b/interface/scopeguard.h @@ -11,9 +11,9 @@ This family of macros is similar to wxON_BLOCK_EXIT but calls a method of the given object instead of a free function. */ -wxON_BLOCK_EXIT_OBJ0(obj, method); -wxON_BLOCK_EXIT_OBJ1(obj, method, p1); -wxON_BLOCK_EXIT_OBJ2(obj, method, p1, p2); +wxON_BLOCK_EXIT_OBJ0(obj, method); +wxON_BLOCK_EXIT_OBJ1(obj, method, p1); +wxON_BLOCK_EXIT_OBJ2(obj, method, p1, p2); //@} @@ -33,10 +33,10 @@ wxON_BLOCK_EXIT_OBJ2(obj, method, p1, p2); published in December 2000 issue of C/C++ Users Journal for more details. - @sa wxON_BLOCK_EXIT_OBJ + @see wxON_BLOCK_EXIT_OBJ */ wxON_BLOCK_EXIT0(func); -wxON_BLOCK_EXIT1(func, p1); -wxON_BLOCK_EXIT2(func, p1, p2); +wxON_BLOCK_EXIT1(func, p1); +wxON_BLOCK_EXIT2(func, p1, p2); //@} diff --git a/interface/scrolbar.h b/interface/scrolbar.h index bb043a7685..1b1541ec06 100644 --- a/interface/scrolbar.h +++ b/interface/scrolbar.h @@ -28,7 +28,7 @@ @seealso @ref overview_scrollingoverview "Scrolling overview", @ref - overview_eventhandlingoverview "Event handling overview", wxScrolledWindow + overview_eventhandlingoverview, wxScrolledWindow */ class wxScrollBar : public wxControl { @@ -38,29 +38,23 @@ public: Constructor, creating and showing a scrollbar. @param parent - Parent window. Must be non-@NULL. - + Parent window. Must be non-@NULL. @param id - Window identifier. The value wxID_ANY indicates a default value. - + Window identifier. The value wxID_ANY indicates a default value. @param pos - Window position. If wxDefaultPosition is specified then a default position - is chosen. - + Window position. If 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 wxDefaultSize is specified then a default size + is chosen. @param style - Window style. See wxScrollBar. - + Window style. See wxScrollBar. @param validator - Window validator. - + Window validator. @param name - Window name. + Window name. - @sa Create(), wxValidator + @see Create(), wxValidator */ wxScrollBar(); wxScrollBar(wxWindow* parent, wxWindowID id, @@ -92,28 +86,28 @@ public: that will be scrolled when the user pages up or down. Often it is the same as the thumb size. - @sa SetScrollbar() + @see SetScrollbar() */ int GetPageSize(); /** Returns the length of the scrollbar. - @sa SetScrollbar() + @see SetScrollbar() */ int GetRange(); /** Returns the current position of the scrollbar thumb. - @sa SetThumbPosition() + @see SetThumbPosition() */ int GetThumbPosition(); /** Returns the thumb or 'view' size. - @sa SetScrollbar() + @see SetScrollbar() */ int GetThumbSize(); @@ -121,37 +115,34 @@ public: Sets the scrollbar properties. @param position - The position of the scrollbar in scroll units. - + The position of the scrollbar in scroll units. @param thumbSize - The size of the thumb, or visible portion of the scrollbar, in scroll units. - + The size of the thumb, or visible portion of the scrollbar, in scroll units. @param range - The maximum position of the scrollbar. - + The maximum position of the scrollbar. @param pageSize - The size of the page size in scroll units. This is the number of units - the scrollbar will scroll when it is paged up or down. Often it is the same as - the thumb size. - + The size of the page size in scroll units. This is the number of units + the scrollbar will scroll when it is paged up or down. Often it is the same + as + the thumb size. @param refresh - @true to redraw the scrollbar, @false otherwise. + @true to redraw the scrollbar, @false otherwise. @remarks Let's say you wish to display 50 lines of text, using the same - font. The window is sized so that you can only see 16 - lines at a time. + font. The window is sized so that you can only see 16 + lines at a time. */ virtual void SetScrollbar(int position, int thumbSize, int range, int pageSize, - bool refresh = @true); + bool refresh = true); /** Sets the position of the scrollbar. @param viewStart - The position of the scrollbar thumb. + The position of the scrollbar thumb. - @sa GetThumbPosition() + @see GetThumbPosition() */ void SetThumbPosition(int viewStart); }; diff --git a/interface/scrolwin.h b/interface/scrolwin.h index d9ac775879..acaf77d2f1 100644 --- a/interface/scrolwin.h +++ b/interface/scrolwin.h @@ -107,34 +107,30 @@ public: Constructor. @param parent - Parent window. - + Parent window. @param id - Window identifier. The value wxID_ANY indicates a default value. - + Window identifier. The value wxID_ANY indicates a default value. @param pos - Window position. If a position of (-1, -1) is specified then a default position - is chosen. - + Window position. If a position of (-1, -1) is specified then a default + position + is chosen. @param size - Window size. If a size of (-1, -1) is specified then the window is sized - appropriately. - + Window size. If a size of (-1, -1) is specified then the window is sized + appropriately. @param style - Window style. See wxScrolledWindow. - + Window style. See wxScrolledWindow. @param name - Window name. + Window name. @remarks The window is initially created without visible scrollbars. Call - SetScrollbars() to specify how big - the virtual window size should be. + SetScrollbars() to specify how big the + virtual window size should be. */ wxScrolledWindow(); wxScrolledWindow(wxWindow* parent, wxWindowID id = -1, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, - long style = wxHSCROLL | wxVSCROLL, + long style = wxHSCROLL | wxVSCROLL, const wxString& name = "scrolledWindow"); //@} @@ -151,9 +147,9 @@ public: (as always), but the logical coordinates are (0, 10) and so the call to CalcScrolledPosition(0, 10, xx, yy) will return 0 in yy. - @sa CalcUnscrolledPosition() + @see CalcUnscrolledPosition() */ - void CalcScrolledPosition(int x, int y, int * xx, int * yy); + void CalcScrolledPosition(int x, int y, int* xx, int* yy); /** Translates the device coordinates to the logical ones. For example, if a window @@ -163,9 +159,9 @@ public: (as always), but the logical coordinates are (0, 10) and so the call to CalcUnscrolledPosition(0, 0, xx, yy) will return 10 in yy. - @sa CalcScrolledPosition() + @see CalcScrolledPosition() */ - void CalcUnscrolledPosition(int x, int y, int * xx, int * yy); + void CalcUnscrolledPosition(int x, int y, int* xx, int* yy); /** Creates the window for two-step construction. Derived classes @@ -175,14 +171,13 @@ public: bool Create(wxWindow* parent, wxWindowID id = -1, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, - long style = wxHSCROLL | wxVSCROLL, + long style = wxHSCROLL | wxVSCROLL, const wxString& name = "scrolledWindow"); /** Call this function to prepare the device context for drawing a scrolled image. It sets the device origin according to the current scroll position. - DoPrepareDC is called automatically within the default OnPaint() event handler, so your OnDraw() override will be passed a 'pre-scrolled' device context. However, if you wish to draw @@ -203,13 +198,12 @@ public: is disabled. @param xScrolling - If @true, enables physical scrolling in the x direction. - + If @true, enables physical scrolling in the x direction. @param yScrolling - If @true, enables physical scrolling in the y direction. + If @true, enables physical scrolling in the y direction. @remarks Physical scrolling may not be available on all platforms. Where - it is available, it is enabled by default. + it is available, it is enabled by default. */ void EnableScrolling(bool xScrolling, bool yScrolling); @@ -219,12 +213,11 @@ public: scrolling in that direction. @param xUnit - Receives the number of pixels per horizontal unit. - + Receives the number of pixels per horizontal unit. @param yUnit - Receives the number of pixels per vertical unit. + Receives the number of pixels per vertical unit. - @sa SetScrollbars(), GetVirtualSize() + @see SetScrollbars(), GetVirtualSize() */ void GetScrollPixelsPerUnit(int* xUnit, int* yUnit); @@ -232,21 +225,20 @@ public: Get the position at which the visible portion of the window starts. @param x - Receives the first visible x position in scroll units. - + Receives the first visible x position in scroll units. @param y - Receives the first visible y position in scroll units. + Receives the first visible y position in scroll units. @remarks If either of the scrollbars is not at the home position, x - and/or y will be greater than zero. Combined with - wxWindow::GetClientSize, the application can use this - function to efficiently redraw only the visible - portion of the window. The positions are in logical - scroll units, not pixels, so to convert to pixels you - will have to multiply by the number of pixels per - scroll increment. - - @sa SetScrollbars() + and/or y will be greater than zero. Combined with + wxWindow::GetClientSize, the application can use this + function to efficiently redraw only the visible portion + of the window. The positions are in logical scroll + units, not pixels, so to convert to pixels you will + have to multiply by the number of pixels per scroll + increment. + + @see SetScrollbars() */ void GetViewStart(int* x, int* y); @@ -256,15 +248,14 @@ public: visible). @param x - Receives the length of the scrollable window, in pixels. - + Receives the length of the scrollable window, in pixels. @param y - Receives the height of the scrollable window, in pixels. + Receives the height of the scrollable window, in pixels. @remarks Use wxDC::DeviceToLogicalX and wxDC::DeviceToLogicalY to - translate these units to logical units. + translate these units to logical units. - @sa SetScrollbars(), GetScrollPixelsPerUnit() + @see SetScrollbars(), GetScrollPixelsPerUnit() */ void GetVirtualSize(int* x, int* y); @@ -277,7 +268,6 @@ public: Called by the default paint event handler to allow the application to define painting behaviour without having to worry about calling DoPrepareDC(). - Instead of overriding this function you may also just process the paint event in the derived class as usual, but then you will have to call DoPrepareDC() yourself. @@ -296,18 +286,17 @@ public: Scrolls a window so the view start is at the given point. @param x - The x position to scroll to, in scroll units. - + The x position to scroll to, in scroll units. @param y - The y position to scroll to, in scroll units. + The y position to scroll to, in scroll units. @remarks The positions are in scroll units, not pixels, so to convert to - pixels you will have to multiply by the number of - pixels per scroll increment. If either parameter is - -1, that position will be ignored (no change in that - direction). + pixels you will have to multiply by the number of + pixels per scroll increment. If either parameter is -1, + that position will be ignored (no change in that + direction). - @sa SetScrollbars(), GetScrollPixelsPerUnit() + @see SetScrollbars(), GetScrollPixelsPerUnit() */ void Scroll(int x, int y); @@ -321,42 +310,36 @@ public: Sets up vertical and/or horizontal scrollbars. @param pixelsPerUnitX - Pixels per scroll unit in the horizontal direction. - + Pixels per scroll unit in the horizontal direction. @param pixelsPerUnitY - Pixels per scroll unit in the vertical direction. - + Pixels per scroll unit in the vertical direction. @param noUnitsX - Number of units in the horizontal direction. - + Number of units in the horizontal direction. @param noUnitsY - Number of units in the vertical direction. - + Number of units in the vertical direction. @param xPos - Position to initialize the scrollbars in the horizontal direction, in scroll - units. - + Position to initialize the scrollbars in the horizontal direction, in + scroll units. @param yPos - Position to initialize the scrollbars in the vertical direction, in scroll + Position to initialize the scrollbars in the vertical direction, in scroll units. - @param noRefresh - Will not refresh window if @true. + Will not refresh window if @true. @remarks The first pair of parameters give the number of pixels per - 'scroll step', i.e. amount moved when the up or down - scroll arrows are pressed. The second pair gives the - length of scrollbar in scroll steps, which sets the - size of the virtual window. + 'scroll step', i.e. amount moved when the up or down + scroll arrows are pressed. The second pair gives the + length of scrollbar in scroll steps, which sets the + size of the virtual window. - @sa wxWindow::SetVirtualSize + @see wxWindow::SetVirtualSize */ void SetScrollbars(int pixelsPerUnitX, int pixelsPerUnitY, int noUnitsX, int noUnitsY, int xPos = 0, int yPos = 0, - bool noRefresh = @false); + bool noRefresh = false); /** Call this function to tell wxScrolledWindow to perform the actual scrolling on diff --git a/interface/settings.h b/interface/settings.h index 10ff1cea2e..2ccb88d62d 100644 --- a/interface/settings.h +++ b/interface/settings.h @@ -31,201 +31,160 @@ public: /** Returns a system colour. - - @e index can be one of: - + @a index can be one of: @b wxSYS_COLOUR_SCROLLBAR - The scrollbar grey area. @b wxSYS_COLOUR_BACKGROUND - The desktop colour. @b wxSYS_COLOUR_ACTIVECAPTION - Active window caption. @b wxSYS_COLOUR_INACTIVECAPTION - Inactive window caption. @b wxSYS_COLOUR_MENU - Menu background. @b wxSYS_COLOUR_WINDOW - Window background. @b wxSYS_COLOUR_WINDOWFRAME - Window frame. @b wxSYS_COLOUR_MENUTEXT - Menu text. @b wxSYS_COLOUR_WINDOWTEXT - Text in windows. @b wxSYS_COLOUR_CAPTIONTEXT - Text in caption, size box and scrollbar arrow box. @b wxSYS_COLOUR_ACTIVEBORDER - Active window border. @b wxSYS_COLOUR_INACTIVEBORDER - Inactive window border. @b wxSYS_COLOUR_APPWORKSPACE - Background colour MDI applications. @b wxSYS_COLOUR_HIGHLIGHT - Item(s) selected in a control. @b wxSYS_COLOUR_HIGHLIGHTTEXT - Text of item(s) selected in a control. @b wxSYS_COLOUR_BTNFACE - Face shading on push buttons. @b wxSYS_COLOUR_BTNSHADOW - Edge shading on push buttons. @b wxSYS_COLOUR_GRAYTEXT - Greyed (disabled) text. @b wxSYS_COLOUR_BTNTEXT - Text on push buttons. @b wxSYS_COLOUR_INACTIVECAPTIONTEXT - Colour of text in active captions. @b wxSYS_COLOUR_BTNHIGHLIGHT - Highlight colour for buttons (same as wxSYS_COLOUR_3DHILIGHT). @b wxSYS_COLOUR_3DDKSHADOW - Dark shadow for three-dimensional display elements. @b wxSYS_COLOUR_3DLIGHT - Light colour for three-dimensional display elements. @b wxSYS_COLOUR_INFOTEXT - Text colour for tooltip controls. @b wxSYS_COLOUR_INFOBK - Background colour for tooltip controls. @b wxSYS_COLOUR_DESKTOP - Same as wxSYS_COLOUR_BACKGROUND. @b wxSYS_COLOUR_3DFACE - Same as wxSYS_COLOUR_BTNFACE. @b wxSYS_COLOUR_3DSHADOW - Same as wxSYS_COLOUR_BTNSHADOW. @b wxSYS_COLOUR_3DHIGHLIGHT - Same as wxSYS_COLOUR_BTNHIGHLIGHT. @b wxSYS_COLOUR_3DHILIGHT - Same as wxSYS_COLOUR_BTNHIGHLIGHT. @b wxSYS_COLOUR_BTNHILIGHT - Same as wxSYS_COLOUR_BTNHIGHLIGHT. */ static wxColour GetColour(wxSystemColour index); /** Returns a system font. - - @e index can be one of: - + @a index can be one of: @b wxSYS_OEM_FIXED_FONT - Original equipment manufacturer dependent fixed-pitch font. @b wxSYS_ANSI_FIXED_FONT - Windows fixed-pitch font. @b wxSYS_ANSI_VAR_FONT - Windows variable-pitch (proportional) font. @b wxSYS_SYSTEM_FONT - System font. @b wxSYS_DEVICE_DEFAULT_FONT - Device-dependent font (Windows NT only). @b wxSYS_DEFAULT_GUI_FONT - Default font for user interface objects such as menus and dialog boxes. Note that with modern GUIs nothing guarantees that the same font is used for all GUI elements, so some controls @@ -236,208 +195,169 @@ public: /** Returns the value of a system metric, or -1 if the metric is not supported on the current system. - The value of @e win determines if the metric returned is a global value or + The value of @a win determines if the metric returned is a global value or a wxWindow based value, in which case it might determine the widget, the display the window is on, or something similar. The window given should be as close to the metric as possible (e.g a wxTopLevelWindow in case of the wxSYS_CAPTION_Y metric). - - @e index can be one of: - + @a index can be one of: @b wxSYS_MOUSE_BUTTONS - Number of buttons on mouse, or zero if no mouse was installed. @b wxSYS_BORDER_X - Width of single border. @b wxSYS_BORDER_Y - Height of single border. @b wxSYS_CURSOR_X - Width of cursor. @b wxSYS_CURSOR_Y - Height of cursor. @b wxSYS_DCLICK_X - Width in pixels of rectangle within which two successive mouse clicks must fall to generate a double-click. @b wxSYS_DCLICK_Y - Height in pixels of rectangle within which two successive mouse clicks must fall to generate a double-click. @b wxSYS_DCLICK_MSEC - Maximal time, in milliseconds, which may pass between subsequent clicks for a double click to be generated. @b wxSYS_DRAG_X - Width in pixels of a rectangle centered on a drag point to allow for limited movement of the mouse pointer before a drag operation begins. @b wxSYS_DRAG_Y - Height in pixels of a rectangle centered on a drag point to allow for limited movement of the mouse pointer before a drag operation begins. @b wxSYS_EDGE_X - Width of a 3D border, in pixels. @b wxSYS_EDGE_Y - Height of a 3D border, in pixels. @b wxSYS_HSCROLL_ARROW_X - Width of arrow bitmap on horizontal scrollbar. @b wxSYS_HSCROLL_ARROW_Y - Height of arrow bitmap on horizontal scrollbar. @b wxSYS_HTHUMB_X - Width of horizontal scrollbar thumb. @b wxSYS_ICON_X - The default width of an icon. @b wxSYS_ICON_Y - The default height of an icon. @b wxSYS_ICONSPACING_X - Width of a grid cell for items in large icon view, in pixels. Each item fits into a rectangle of this size when arranged. @b wxSYS_ICONSPACING_Y - Height of a grid cell for items in large icon view, in pixels. Each item fits into a rectangle of this size when arranged. @b wxSYS_WINDOWMIN_X - Minimum width of a window. @b wxSYS_WINDOWMIN_Y - Minimum height of a window. @b wxSYS_SCREEN_X - Width of the screen in pixels. @b wxSYS_SCREEN_Y - Height of the screen in pixels. @b wxSYS_FRAMESIZE_X - Width of the window frame for a wxTHICK_FRAME window. @b wxSYS_FRAMESIZE_Y - Height of the window frame for a wxTHICK_FRAME window. @b wxSYS_SMALLICON_X - Recommended width of a small icon (in window captions, and small icon view). @b wxSYS_SMALLICON_Y - Recommended height of a small icon (in window captions, and small icon view). @b wxSYS_HSCROLL_Y - Height of horizontal scrollbar in pixels. @b wxSYS_VSCROLL_X - Width of vertical scrollbar in pixels. @b wxSYS_VSCROLL_ARROW_X - Width of arrow bitmap on a vertical scrollbar. @b wxSYS_VSCROLL_ARROW_Y - Height of arrow bitmap on a vertical scrollbar. @b wxSYS_VTHUMB_Y - Height of vertical scrollbar thumb. @b wxSYS_CAPTION_Y - Height of normal caption area. @b wxSYS_MENU_Y - Height of single-line menu bar. @b wxSYS_NETWORK_PRESENT - 1 if there is a network present, 0 otherwise. @b wxSYS_PENWINDOWS_PRESENT - 1 if PenWindows is installed, 0 otherwise. @b wxSYS_SHOW_SOUNDS - Non-zero if the user requires an application to present information visually in situations where it would otherwise present the information only in audible form; zero @@ -445,12 +365,11 @@ public: @b wxSYS_SWAP_BUTTONS - Non-zero if the meanings of the left and right mouse buttons are swapped; zero otherwise. - @e win is a pointer to the window for which the metric is requested. - Specifying the @e win parameter is encouraged, because some metrics on some + @a win is a pointer to the window for which the metric is requested. + Specifying the @a win parameter is encouraged, because some metrics on some ports are not supported without one, or they might be capable of reporting better values if given one. If a window does not make sense for a metric, @@ -458,35 +377,29 @@ public: cursor width is requested with wxSYS_CURSOR_X. */ - static int GetMetric(wxSystemMetric index, wxWindow* win = @NULL); + static int GetMetric(wxSystemMetric index, wxWindow* win = NULL); /** Returns the screen type. The return value is one of: - @b wxSYS_SCREEN_NONE - Undefined screen type @b wxSYS_SCREEN_TINY - Tiny screen, less than 320x240 @b wxSYS_SCREEN_PDA - PDA screen, 320x240 or more but less than 640x480 @b wxSYS_SCREEN_SMALL - Small screen, 640x480 or more but less than 800x600 @b wxSYS_SCREEN_DESKTOP - Desktop screen, 800x600 or more */ static wxSystemScreenType GetScreenType(); diff --git a/interface/sizer.h b/interface/sizer.h index db38e760b3..0928d5b78f 100644 --- a/interface/sizer.h +++ b/interface/sizer.h @@ -51,7 +51,6 @@ public: /** Adds a button to the wxStdDialogButtonSizer. The button must have one of the following identifiers: - wxID_OK wxID_YES wxID_SAVE @@ -349,21 +348,19 @@ public: /** Sets the alignment of this wxSizerFlags to @e align. - Note that if this method is not called, the wxSizerFlags has no specified alignment. - @sa Top(), Left(), Right(), - Bottom(), Centre() + @see Top(), Left(), Right(), + Bottom(), Centre() */ wxSizerFlags Align(int align = 0); //@{ /** Sets the wxSizerFlags to have a border of a number of pixels specified by - @e borderinpixels with the directions specified by @e direction. - - In the overloaded version without @e borderinpixels parameter, the border of + @a borderinpixels with the directions specified by @e direction. + In the overloaded version without @a borderinpixels parameter, the border of default size, as returned by GetDefaultBorder(), is used. */ @@ -374,7 +371,7 @@ public: /** Aligns the object to the bottom, shortcut for @c Align(wxALIGN_BOTTOM) - @sa Align() + @see Align() */ wxSizerFlags Bottom(); @@ -389,7 +386,7 @@ public: wxSizerFlags Centre(); /** - Sets the border in the given @e direction having twice the default border + Sets the border in the given @a direction having twice the default border size. */ wxSizerFlags DoubleBorder(int direction = wxALL); @@ -419,7 +416,7 @@ public: /** Aligns the object to the left, shortcut for @c Align(wxALIGN_LEFT) - @sa Align() + @see Align() */ wxSizerFlags Left(); @@ -431,7 +428,7 @@ public: /** Aligns the object to the right, shortcut for @c Align(wxALIGN_RIGHT) - @sa Align() + @see Align() */ wxSizerFlags Right(); @@ -444,12 +441,12 @@ public: /** Aligns the object to the top, shortcut for @c Align(wxALIGN_TOP) - @sa Align() + @see Align() */ -#define wxSizerFlags Top() /* implementation is private */ + wxSizerFlags Top(); /** - Sets the border in the given @e direction having thrice the default border + Sets the border in the given @a direction having thrice the default border size. */ wxSizerFlags TripleBorder(int direction = wxALL); @@ -524,10 +521,10 @@ class wxFlexGridSizer : public wxGridSizer public: //@{ /** - Constructor for a wxGridSizer. @e rows and @e cols determine the number of + Constructor for a wxGridSizer. @a rows and @a cols determine the number of columns and rows in the sizer - if either of the parameters is zero, it will be calculated to form the total number of children in the sizer, thus making the - sizer grow dynamically. @e vgap and @e hgap define extra space between + sizer grow dynamically. @a vgap and @a hgap define extra space between all children. */ wxFlexGridSizer(int rows, int cols, int vgap, int hgap); @@ -535,10 +532,9 @@ public: //@} /** - Specifies that column @e idx (starting from zero) should be grown if + Specifies that column @a idx (starting from zero) should be grown if there is extra space available to the sizer. - - The @e proportion parameter has the same meaning as the stretch factor for + The @a proportion parameter has the same meaning as the stretch factor for the sizers except that if all proportions are 0, then all columns are resized equally (instead of not being resized at all). */ @@ -547,9 +543,8 @@ public: /** Specifies that row idx (starting from zero) should be grown if there is extra space available to the sizer. - See AddGrowableCol() for the description - of @e proportion parameter. + of @a proportion parameter. */ void AddGrowableRow(size_t idx, int proportion = 0); @@ -559,7 +554,7 @@ public: @returns One of the following values: - @sa SetFlexibleDirection() + @see SetFlexibleDirection() */ int GetFlexibleDirection(); @@ -569,8 +564,8 @@ public: @returns One of the following values: - @sa SetFlexibleDirection(), - SetNonFlexibleGrowMode() + @see SetFlexibleDirection(), + SetNonFlexibleGrowMode() */ int GetNonFlexibleGrowMode(); @@ -590,7 +585,6 @@ public: or @c wxBOTH (which is the default value). Any other value is ignored. See @ref getflexibledrection() GetFlexibleDirection for the explanation of these values. - Note that this method does not trigger relayout. */ void SetFlexibleDirection(int direction); @@ -599,10 +593,9 @@ public: Specifies how the sizer should grow in the non-flexible direction if there is one (so SetFlexibleDirection() must have - been called previously). Argument @e mode can be one of those documented in + been called previously). Argument @a mode can be one of those documented in GetNonFlexibleGrowMode(), please see there for their explanation. - Note that this method does not trigger relayout. */ void SetNonFlexibleGrowMode(wxFlexSizerGrowMode mode); @@ -699,139 +692,162 @@ public: here: @param window - The window to be added to the sizer. Its initial size (either set explicitly by - the - user or calculated internally when using wxDefaultSize) is interpreted as the - minimal and in many - cases also the initial size. - + The window to be added to the sizer. Its initial size (either set + explicitly by the + user or calculated internally when using wxDefaultSize) is interpreted as + the minimal and in many + cases also the initial size. @param sizer - The (child-)sizer to be added to the sizer. This allows placing a child sizer - in a - sizer and thus to create hierarchies of sizers (typically a vertical box as the - top sizer and several - horizontal boxes on the level beneath). - + The (child-)sizer to be added to the sizer. This allows placing a child + sizer in a + sizer and thus to create hierarchies of sizers (typically a vertical box as + the top sizer and several + horizontal boxes on the level beneath). @param width and height - The dimension of a spacer to be added to the sizer. Adding spacers to sizers - gives more flexibility in the design of dialogs; imagine for example a + The dimension of a spacer to be added to the sizer. Adding spacers to sizers + gives more flexibility in the design of dialogs; imagine for example a horizontal box with two buttons at the - bottom of a dialog: you might want to insert a space between the two buttons - and make that space stretchable - using the proportion flag and the result will be that the left button will be - aligned with the left - side of the dialog and the right button with the right side - the space in + bottom of a dialog: you might want to insert a space between the two + buttons and make that space stretchable + using the proportion flag and the result will be that the left button will + be aligned with the left + side of the dialog and the right button with the right side - the space in between will shrink and grow with - the dialog. - + the dialog. @param proportion - Although the meaning of this parameter is undefined in wxSizer, it is used in - wxBoxSizer - to indicate if a child of a sizer can change its size in the main orientation - of the wxBoxSizer - where - 0 stands for not changeable and a value of more than zero is interpreted + Although the meaning of this parameter is undefined in wxSizer, it is used + in wxBoxSizer + to indicate if a child of a sizer can change its size in the main + orientation of the wxBoxSizer - where + 0 stands for not changeable and a value of more than zero is interpreted relative to the value of other - children of the same wxBoxSizer. For example, you might have a horizontal + children of the same wxBoxSizer. For example, you might have a horizontal wxBoxSizer with three children, two - of which are supposed to change their size with the sizer. Then the two + of which are supposed to change their size with the sizer. Then the two stretchable windows would get a - value of 1 each to make them grow and shrink equally with the sizer's + value of 1 each to make them grow and shrink equally with the sizer's horizontal dimension. - @param flag - This parameter can be used to set a number of flags - which can be combined using the binary OR operator |. Two main - behaviours are defined using these flags. One is the border around a - window: the border parameter determines the border width whereas - the flags given here determine which side(s) of the item that the - border will be added. The other flags determine how the sizer item - behaves when the space allotted to the sizer changes, and is somewhat - dependent on the specific kind of sizer used. + This parameter can be used to set a number of flags + which can be combined using the binary OR operator |. Two main + behaviours are defined using these flags. One is the border around a + window: the border parameter determines the border width whereas + the flags given here determine which side(s) of the item that the + border will be added. The other flags determine how the sizer item + behaves when the space allotted to the sizer changes, and is somewhat + dependent on the specific kind of sizer used. - wxTOP - wxBOTTOM - wxLEFT - wxRIGHT - wxALL + wxTOP - These flags are used to specify which side(s) of - the sizer item the border width will apply to. + wxBOTTOM + wxLEFT - wxEXPAND + wxRIGHT + wxALL - The item will be expanded to fill - the space assigned to the item. - wxSHAPED - The item will be expanded as much - as possible while also maintaining its aspect ratio + These flags are used to specify which side(s) of + the sizer item the border width will apply to. - wxFIXED_MINSIZE - Normally wxSizers will use - GetAdjustedBestSize to - determine what the minimal size of window items should be, and will - use that size to calculate the layout. This allows layouts to - adjust when an item changes and its best size becomes - different. If you would rather have a window item stay the size it - started with then use wxFIXED_MINSIZE. - wxALIGN_CENTER wxALIGN_CENTRE - wxALIGN_LEFT + wxEXPAND - wxALIGN_RIGHT - wxALIGN_TOP - wxALIGN_BOTTOM - wxALIGN_CENTER_VERTICAL wxALIGN_CENTRE_VERTICAL + The item will be expanded to fill + the space assigned to the item. - wxALIGN_CENTER_HORIZONTAL wxALIGN_CENTRE_HORIZONTAL - The wxALIGN flags allow you to - specify the alignment of the item within the space allotted to it by - the sizer, adjusted for the border if any. - @param border - Determines the border width, if the flag - parameter is set to include any border flag. - @param userData - Allows an extra object to be attached to the sizer - item, for use in derived classes when sizing information is more - complex than the proportion and flag will allow for. + wxSHAPED + + + + + The item will be expanded as much + as possible while also maintaining its aspect ratio + + + + + + wxFIXED_MINSIZE + + + + + Normally wxSizers will use + GetAdjustedBestSize to + determine what the minimal size of window items should be, and will + use that size to calculate the layout. This allows layouts to + adjust when an item changes and its best size becomes + different. If you would rather have a window item stay the size it + started with then use wxFIXED_MINSIZE. + + + + + wxALIGN_CENTER wxALIGN_CENTRE + + wxALIGN_LEFT + + wxALIGN_RIGHT + + wxALIGN_TOP + + wxALIGN_BOTTOM + + wxALIGN_CENTER_VERTICAL wxALIGN_CENTRE_VERTICAL + + wxALIGN_CENTER_HORIZONTAL wxALIGN_CENTRE_HORIZONTAL + + + + + The wxALIGN flags allow you to + specify the alignment of the item within the space allotted to it by + the sizer, adjusted for the border if any. + @param border + Determines the border width, if the flag + parameter is set to include any border flag. + @param userData + Allows an extra object to be attached to the sizer + item, for use in derived classes when sizing information is more + complex than the proportion and flag will allow for. @param flags - A wxSizerFlags object that - enables you to specify most of the above parameters more conveniently. + A wxSizerFlags object that + enables you to specify most of the above parameters more conveniently. */ wxSizerItem* Add(wxWindow* window, const wxSizerFlags& flags); wxSizerItem* Add(wxWindow* window, int proportion = 0, int flag = 0, int border = 0, - wxObject* userData = @NULL); + wxObject* userData = NULL); wxSizerItem* Add(wxSizer* sizer, const wxSizerFlags& flags); wxSizerItem* Add(wxSizer* sizer, int proportion = 0, int flag = 0, int border = 0, - wxObject* userData = @NULL); + wxObject* userData = NULL); wxSizerItem* Add(int width, int height, int proportion = 0, int flag = 0, int border = 0, - wxObject* userData = @NULL); + wxObject* userData = NULL); //@} /** @@ -853,51 +869,48 @@ public: wxSize CalcMin(); /** - Detaches all children from the sizer. If @e delete_windows is @true then + Detaches all children from the sizer. If @a delete_windows is @true then child windows will also be deleted. */ - void Clear(bool delete_windows = @false); + void Clear(bool delete_windows = false); /** - Computes client area size for @e window so that it matches the + Computes client area size for @a window so that it matches the sizer's minimal size. Unlike GetMinSize(), this method accounts for other constraints imposed on @e window, namely display's size (returned size will never be too large for the display) and maximum window size if previously set by wxWindow::SetMaxSize. - The returned value is suitable for passing to wxWindow::SetClientSize or wxWindow::SetMinClientSize. - @sa ComputeFittingWindowSize(), Fit() + @see ComputeFittingWindowSize(), Fit() */ wxSize ComputeFittingClientSize(wxWindow* window); /** Like ComputeFittingClientSize(), but converts the result into window size. - The returned value is suitable for passing to wxWindow::SetSize or wxWindow::SetMinSize. - @sa ComputeFittingClientSize(), Fit() + @see ComputeFittingClientSize(), Fit() */ wxSize ComputeFittingWindowSize(wxWindow* window); //@{ /** - Detach a child from the sizer without destroying it. @e window is the window to + Detach a child from the sizer without destroying it. @a window is the window to be - detached, @e sizer is the equivalent sizer and @e index is the position of + detached, @a sizer is the equivalent sizer and @a index is the position of the child in the sizer, typically 0 for the first item. This method does not cause any layout or resizing to take place, call Layout() to update the layout "on screen" after detaching a child from the sizer. - Returns @true if the child item was found and detached, @false otherwise. - @sa Remove() + @see Remove() */ bool Detach(wxWindow* window); bool Detach(wxSizer* sizer); @@ -905,7 +918,7 @@ public: //@} /** - Tell the sizer to resize the @e window so that its client area matches the + Tell the sizer to resize the @a window so that its client area matches the sizer's minimal size (ComputeFittingClientSize() is called to determine it). @@ -913,19 +926,19 @@ public: itself, see sample in the description of wxBoxSizer. Returns the new window size. - @sa ComputeFittingClientSize(), ComputeFittingWindowSize() + @see ComputeFittingClientSize(), ComputeFittingWindowSize() */ -#define wxSize Fit(wxWindow* window) /* implementation is private */ + wxSize Fit(wxWindow* window); /** - Tell the sizer to resize the virtual size of the @e window to match the sizer's + Tell the sizer to resize the virtual size of the @a window to match the sizer's minimal size. This will not alter the on screen size of the window, but may cause the addition/removal/alteration of scrollbars required to view the virtual area in windows which manage it. - @sa wxScrolledWindow::SetScrollbars, SetVirtualSizeHints() + @see wxScrolledWindow::SetScrollbars, SetVirtualSizeHints() */ void FitInside(wxWindow* window); @@ -942,37 +955,33 @@ public: /** Returns the window this sizer is used in or @NULL if none. */ - wxWindow * GetContainingWindow(); + wxWindow* GetContainingWindow(); //@{ /** - Finds item of the sizer which holds given @e window, @e sizer or is located + Finds item of the sizer which holds given @e window, @a sizer or is located in sizer at position @e index. - Use parameter @e recursive to search in subsizers too. - + Use parameter @a recursive to search in subsizers too. Returns pointer to item or @NULL. */ - wxSizerItem * GetItem(wxWindow* window, bool recursive = @false); - wxSizerItem * GetItem(wxSizer* sizer, bool recursive = @false); - wxSizerItem * GetItem(size_t index); + wxSizerItem* GetItem(wxWindow* window, bool recursive = false); + wxSizerItem* GetItem(wxSizer* sizer, bool recursive = false); + wxSizerItem* GetItem(size_t index); //@} /** - Finds item of the sizer which has the given @e id. This @e id is not the + Finds item of the sizer which has the given @e id. This @a id is not the window id but the id of the wxSizerItem itself. This is mainly useful for retrieving the sizers created from XRC resources. - - Use parameter @e recursive to search in subsizers too. - + Use parameter @a recursive to search in subsizers too. Returns pointer to item or @NULL. */ - wxSizerItem * GetItemById(int id, bool recursive = @false); + wxSizerItem* GetItemById(int id, bool recursive = false); /** Returns the minimal size of the sizer. This is either the combined minimal size of all the children and their borders or the minimal size set by SetMinSize(), depending on which is bigger. - Note that the returned value is client size, not window size. In particular, if you use the value to set toplevel window's minimal or actual size, use wxWindow::SetMinClientSize @@ -996,26 +1005,26 @@ public: /** Hides the @e window, @e sizer, or item at @e index. To make a sizer item disappear, use Hide() followed by Layout(). - Use parameter @e recursive to hide elements found in subsizers. - + Use parameter @a recursive to hide elements found in subsizers. Returns @true if the child item was found, @false otherwise. - @sa IsShown(), Show() + @see IsShown(), Show() */ - bool Hide(wxWindow* window, bool recursive = @false); - bool Hide(wxSizer* sizer, bool recursive = @false); + bool Hide(wxWindow* window, bool recursive = false); + bool Hide(wxSizer* sizer, bool recursive = false); bool Hide(size_t index); //@} //@{ /** Insert a child into the sizer before any existing item at + See Add() for the meaning of the other parameters. @param index. index - The position this child should assume in the sizer. + The position this child should assume in the sizer. */ wxSizerItem* Insert(size_t index, wxWindow* window, const wxSizerFlags& flags); @@ -1023,19 +1032,19 @@ public: int proportion = 0, int flag = 0, int border = 0, - wxObject* userData = @NULL); + wxObject* userData = NULL); wxSizerItem* Insert(size_t index, wxSizer* sizer, const wxSizerFlags& flags); wxSizerItem* Insert(size_t index, wxSizer* sizer, int proportion = 0, int flag = 0, int border = 0, - wxObject* userData = @NULL); + wxObject* userData = NULL); wxSizerItem* Insert(size_t index, int width, int height, int proportion = 0, int flag = 0, int border = 0, - wxObject* userData = @NULL); + wxObject* userData = NULL); //@} /** @@ -1052,9 +1061,9 @@ public: //@{ /** - Returns @true if the @e window, @e sizer, or item at @e index is shown. + Returns @true if the @e window, @e sizer, or item at @a index is shown. - @sa Hide(), Show() + @see Hide(), Show() */ bool IsShown(wxWindow* window); bool IsShown(wxSizer* sizer); @@ -1078,18 +1087,18 @@ public: wxSizerItem* Prepend(wxWindow* window, int proportion = 0, int flag = 0, int border = 0, - wxObject* userData = @NULL); + wxObject* userData = NULL); wxSizerItem* Prepend(wxSizer* sizer, const wxSizerFlags& flags); wxSizerItem* Prepend(wxSizer* sizer, int proportion = 0, int flag = 0, int border = 0, - wxObject* userData = @NULL); + wxObject* userData = NULL); wxSizerItem* Prepend(int width, int height, int proportion = 0, int flag = 0, - int border= 0, - wxObject* userData = @NULL); + int border = 0, + wxObject* userData = NULL); //@} /** @@ -1115,17 +1124,15 @@ public: /** Removes a child from the sizer and destroys it if it is a sizer or a spacer, but not if it is a window (because windows are owned by their parent window, - not the sizer). @e sizer is the wxSizer to be removed, - @e index is the position of the child in the sizer, e.g. 0 for the first item. + not the sizer). @a sizer is the wxSizer to be removed, + @a index is the position of the child in the sizer, e.g. 0 for the first item. This method does not cause any layout or resizing to take place, call Layout() to update the layout "on screen" after removing a child from the sizer. - @b NB: The method taking a wxWindow* parameter is deprecated as it does not destroy the window as would usually be expected from Remove. You should use Detach() in new code instead. There is currently no wxSizer method that will both detach and destroy a wxWindow item. - Returns @true if the child item was found and removed, @false otherwise. */ bool Remove(wxWindow* window); @@ -1135,23 +1142,21 @@ public: //@{ /** - Detaches the given @e oldwin, @e oldsz child from the sizer and + Detaches the given @e oldwin, @a oldsz child from the sizer and replaces it with the given window, sizer, or wxSizerItem. - The detached child is removed @b only if it is a sizer or a spacer (because windows are owned by their parent window, not the sizer). + Use parameter @a recursive to search the given element recursively in subsizers. - Use parameter @e recursive to search the given element recursively in subsizers. This method does not cause any layout or resizing to take place, call Layout() to update the layout "on screen" after replacing a child from the sizer. - Returns @true if the child item was found and removed, @false otherwise. */ bool Replace(wxWindow* oldwin, wxWindow* newwin, - bool recursive = @false); + bool recursive = false); bool Replace(wxSizer* oldsz, wxSizer* newsz, - bool recursive = @false); + bool recursive = false); bool Remove(size_t oldindex, wxSizerItem* newitem); //@} @@ -1194,11 +1199,10 @@ public: /** This method first calls Fit() and then wxTopLevelWindow::SetSizeHints on the @e window - passed to it. This only makes sense when @e window is actually a + passed to it. This only makes sense when @a window is actually a wxTopLevelWindow such as a wxFrame or a wxDialog, since SetSizeHints only has any effect in these classes. It does nothing in normal windows or controls. - This method is implicitly used by wxWindow::SetSizerAndFit which is commonly invoked in the constructor of a toplevel window itself (see the sample in the description of wxBoxSizer) if the @@ -1207,12 +1211,12 @@ public: void SetSizeHints(wxWindow* window); /** - Tell the sizer to set the minimal size of the @e window virtual area to match + Tell the sizer to set the minimal size of the @a window virtual area to match the sizer's minimal size. For windows with managed scrollbars this will set them appropriately. - @sa wxScrolledWindow::SetScrollbars + @see wxScrolledWindow::SetScrollbars */ void SetVirtualSizeHints(wxWindow* window); @@ -1220,17 +1224,16 @@ public: /** Shows or hides the @e window, @e sizer, or item at @e index. To make a sizer item disappear or reappear, use Show() followed by Layout(). - Use parameter @e recursive to show or hide elements found in subsizers. - + Use parameter @a recursive to show or hide elements found in subsizers. Returns @true if the child item was found, @false otherwise. - @sa Hide(), IsShown() + @see Hide(), IsShown() */ - bool Show(wxWindow* window, bool show = @true, - bool recursive = @false); - bool Show(wxSizer* sizer, bool show = @true, - bool recursive = @false); - bool Show(size_t index, bool show = @true); + bool Show(wxWindow* window, bool show = true, + bool recursive = false); + bool Show(wxSizer* sizer, bool show = true, + bool recursive = false); + bool Show(size_t index, bool show = true); //@} }; @@ -1255,10 +1258,10 @@ class wxGridSizer : public wxSizer public: //@{ /** - Constructor for a wxGridSizer. @e rows and @e cols determine the number of + Constructor for a wxGridSizer. @a rows and @a cols determine the number of columns and rows in the sizer - if either of the parameters is zero, it will be calculated to form the total number of children in the sizer, thus making the - sizer grow dynamically. @e vgap and @e hgap define extra space between + sizer grow dynamically. @a vgap and @a hgap define extra space between all children. */ wxGridSizer(int rows, int cols, int vgap, int hgap); @@ -1331,7 +1334,6 @@ public: The first constructor uses an already existing static box. It takes the associated static box and the orientation @e orient, which can be either @c wxVERTICAL or @c wxHORIZONTAL as parameters. - The second one creates a new static box with the given label and parent window. */ wxStaticBoxSizer(wxStaticBox* box, int orient); @@ -1368,7 +1370,7 @@ class wxBoxSizer : public wxSizer { public: /** - Constructor for a wxBoxSizer. @e orient may be either of wxVERTICAL + Constructor for a wxBoxSizer. @a orient may be either of wxVERTICAL or wxHORIZONTAL for creating either a column sizer or a row sizer. */ wxBoxSizer(int orient); diff --git a/interface/slider.h b/interface/slider.h index 6af9ecf1c0..68e45f9928 100644 --- a/interface/slider.h +++ b/interface/slider.h @@ -46,7 +46,7 @@ @appearance{slider.png} @seealso - @ref overview_eventhandlingoverview "Event handling overview", wxScrollBar + @ref overview_eventhandlingoverview, wxScrollBar */ class wxSlider : public wxControl { @@ -56,34 +56,26 @@ public: Constructor, creating and showing a slider. @param parent - Parent window. Must not be @NULL. - + Parent window. Must not be @NULL. @param id - Window identifier. The value wxID_ANY indicates a default value. - + Window identifier. The value wxID_ANY indicates a default value. @param value - Initial position for the slider. - + Initial position for the slider. @param minValue - Minimum slider position. - + Minimum slider position. @param maxValue - Maximum slider position. - + Maximum slider position. @param size - Window size. If wxDefaultSize is specified then a default size is - chosen. - + Window size. If wxDefaultSize is specified then a default size + is chosen. @param style - Window style. See wxSlider. - + Window style. See wxSlider. @param validator - Window validator. - + Window validator. @param name - Window name. + Window name. - @sa Create(), wxValidator + @see Create(), wxValidator */ wxSlider(); wxSlider(wxWindow* parent, wxWindowID id, int value, @@ -129,28 +121,28 @@ public: /** Returns the line size. - @sa SetLineSize() + @see SetLineSize() */ int GetLineSize(); /** Gets the maximum slider value. - @sa GetMin(), SetRange() + @see GetMin(), SetRange() */ int GetMax(); /** Gets the minimum slider value. - @sa GetMin(), SetRange() + @see GetMin(), SetRange() */ int GetMin(); /** Returns the page size. - @sa SetPageSize() + @see SetPageSize() */ int GetPageSize(); @@ -159,7 +151,7 @@ public: @remarks Windows 95 only. - @sa GetSelStart(), SetSelection() + @see GetSelStart(), SetSelection() */ int GetSelEnd(); @@ -168,7 +160,7 @@ public: @remarks Windows 95 only. - @sa GetSelEnd(), SetSelection() + @see GetSelEnd(), SetSelection() */ int GetSelStart(); @@ -177,7 +169,7 @@ public: @remarks Windows 95 only. - @sa SetThumbLength() + @see SetThumbLength() */ int GetThumbLength(); @@ -186,14 +178,14 @@ public: @remarks Windows 95 only. - @sa SetTickFreq() + @see SetTickFreq() */ int GetTickFreq(); /** Gets the current slider value. - @sa GetMin(), GetMax(), SetValue() + @see GetMin(), GetMax(), SetValue() */ int GetValue(); @@ -201,9 +193,10 @@ public: Sets the line size for the slider. @param lineSize - The number of steps the slider moves when the user moves it up or down a line. + The number of steps the slider moves when the user moves it up or down a + line. - @sa GetLineSize() + @see GetLineSize() */ void SetLineSize(int lineSize); @@ -211,16 +204,16 @@ public: Sets the page size for the slider. @param pageSize - The number of steps the slider moves when the user pages up or down. + The number of steps the slider moves when the user pages up or down. - @sa GetPageSize() + @see GetPageSize() */ void SetPageSize(int pageSize); /** Sets the minimum and maximum slider values. - @sa GetMin(), GetMax() + @see GetMin(), GetMax() */ void SetRange(int minValue, int maxValue); @@ -228,14 +221,13 @@ public: Sets the selection. @param startPos - The selection start position. - + The selection start position. @param endPos - The selection end position. + The selection end position. @remarks Windows 95 only. - @sa GetSelStart(), GetSelEnd() + @see GetSelStart(), GetSelEnd() */ void SetSelection(int startPos, int endPos); @@ -243,11 +235,11 @@ public: Sets the slider thumb length. @param len - The thumb length. + The thumb length. @remarks Windows 95 only. - @sa GetThumbLength() + @see GetThumbLength() */ void SetThumbLength(int len); @@ -255,11 +247,11 @@ public: Sets a tick position. @param tickPos - The tick position. + The tick position. @remarks Windows 95 only. - @sa SetTickFreq() + @see SetTickFreq() */ void SetTick(int tickPos); @@ -267,16 +259,15 @@ public: Sets the tick mark frequency and position. @param n - Frequency. For example, if the frequency is set to two, a tick mark is + Frequency. For example, if the frequency is set to two, a tick mark is displayed for - every other increment in the slider's range. - + every other increment in the slider's range. @param pos - Position. Must be greater than zero. TODO: what is this for? + Position. Must be greater than zero. TODO: what is this for? @remarks Windows 95 only. - @sa GetTickFreq() + @see GetTickFreq() */ void SetTickFreq(int n, int pos); @@ -284,7 +275,7 @@ public: Sets the slider position. @param value - The slider position. + The slider position. */ void SetValue(int value); }; diff --git a/interface/snglinst.h b/interface/snglinst.h index a22af19454..4090dc8c28 100644 --- a/interface/snglinst.h +++ b/interface/snglinst.h @@ -71,7 +71,6 @@ public: /** Destructor frees the associated resources. - Note that it is not virtual, this class is not meant to be used polymorphically */ ~wxSingleInstanceChecker(); @@ -83,19 +82,18 @@ public: had been used is an error. @param name - must be given and be as unique as possible. It is used as the - mutex name under Win32 and the lock file name under Unix. - GetAppName() and wxGetUserId() - are commonly used to construct this parameter. - + must be given and be as unique as possible. It is used as the + mutex name under Win32 and the lock file name under Unix. + GetAppName() and wxGetUserId() + are commonly used to construct this parameter. @param path - is optional and is ignored under Win32 and used as the directory to - create the lock file in under Unix (default is - wxGetHomeDir()) + is optional and is ignored under Win32 and used as the directory to + create the lock file in under Unix (default is + wxGetHomeDir()) @returns Returns @false if initialization failed, it doesn't mean that - another instance is running - use IsAnotherRunning() - to check for it. + another instance is running - use IsAnotherRunning() + to check for it. */ bool Create(const wxString& name, const wxString& path = wxEmptyString); diff --git a/interface/socket.h b/interface/socket.h index d57b844f1f..08788d2c37 100644 --- a/interface/socket.h +++ b/interface/socket.h @@ -81,10 +81,9 @@ public: @ref wxSocketBase::isok wxSocketBase:IsOk. @param address - Specifies the local address for the server (e.g. port number). - + Specifies the local address for the server (e.g. port number). @param flags - Socket flags (See wxSocketBase::SetFlags) + Socket flags (See wxSocketBase::SetFlags) */ wxSocketServer(const wxSockAddress& address, wxSocketFlags flags = wxSOCKET_NONE); @@ -98,12 +97,10 @@ public: Accepts an incoming connection request, and creates a new wxSocketBase object which represents the server-side of the connection. - - If @e wait is @true and there are no pending connections to be + If @a wait is @true and there are no pending connections to be accepted, it will wait for the next incoming connection to arrive. @b Warning: This will block the GUI. - - If @e wait is @false, it will try to accept a pending connection + If @a wait is @false, it will try to accept a pending connection if there is one, but it will always return immediately without blocking the GUI. If you want to use Accept in this way, you can either check for incoming connections with WaitForAccept() @@ -111,25 +108,25 @@ public: that there is an incoming connection waiting to be accepted. @returns Returns an opened socket connection, or @NULL if an error - occurred or if the wait parameter was @false and there - were no pending connections. + occurred or if the wait parameter was @false and there + were no pending connections. - @sa WaitForAccept(), wxSocketBase::SetNotify, - wxSocketBase::Notify, AcceptWith() + @see WaitForAccept(), wxSocketBase::SetNotify, + wxSocketBase::Notify, AcceptWith() */ - wxSocketBase * Accept(bool wait = @true); + wxSocketBase* Accept(bool wait = true); /** Accept an incoming connection using the specified socket object. @param socket - Socket to be initialized + Socket to be initialized @returns Returns @true on success, or @false if an error occurred or if the - wait parameter was @false and there were no pending - connections. + wait parameter was @false and there were no pending + connections. */ - bool AcceptWith(wxSocketBase& socket, bool wait = @true); + bool AcceptWith(wxSocketBase& socket, bool wait = true); /** This function waits for an incoming connection. Use it if you want to call @@ -138,15 +135,14 @@ public: to be accepted. @param seconds - Number of seconds to wait. - If -1, it will wait for the default timeout, - as set with SetTimeout. - + Number of seconds to wait. + If -1, it will wait for the default timeout, + as set with SetTimeout. @param millisecond - Number of milliseconds to wait. + Number of milliseconds to wait. @returns Returns @true if an incoming connection arrived, @false if the - timeout elapsed. + timeout elapsed. */ bool WaitForAccept(long seconds = -1, long millisecond = 0); }; @@ -170,9 +166,7 @@ public: /** Internally, this is the same as setting the IP address to @b INADDR_ANY. - On IPV4 implementations, 0.0.0.0 - On IPV6 implementations, :: @returns Returns @true on success, @false if something went wrong. @@ -182,7 +176,6 @@ public: /** Internally, this is the same as setting the IP address to @b INADDR_BROADCAST. - On IPV4 implementations, 255.255.255.255 @returns Returns @true on success, @false if something went wrong. @@ -209,9 +202,7 @@ public: /** Set address to localhost. - On IPV4 implementations, 127.0.0.1 - On IPV6 implementations, ::1 @returns Returns @true on success, @false if something went wrong. @@ -247,7 +238,7 @@ public: Constructor. @param flags - Socket flags (See wxSocketBase::SetFlags) + Socket flags (See wxSocketBase::SetFlags) */ wxSocketClient(wxSocketFlags flags = wxSOCKET_NONE); @@ -259,11 +250,9 @@ public: //@{ /** Connects to a server using the specified address. - - If @e wait is @true, Connect will wait until the connection + If @a wait is @true, Connect will wait until the connection completes. @b Warning: This will block the GUI. - - If @e wait is @false, Connect will try to establish the connection and + If @a wait is @false, Connect will try to establish the connection and return immediately, without blocking the GUI. When used this way, even if Connect returns @false, the connection request can be completed later. To detect this, use WaitOnConnect(), @@ -271,25 +260,23 @@ public: and @b wxSOCKET_LOST events (for connection failure). @param address - Address of the server. - + Address of the server. @param local - Bind to the specified local address and port before connecting. - The local address and port can also be set using SetLocal, - and then using the 2-parameter Connect method. - + Bind to the specified local address and port before connecting. + The local address and port can also be set using SetLocal, + and then using the 2-parameter Connect method. @param wait - If @true, waits for the connection to complete. + If @true, waits for the connection to complete. @returns Returns @true if the connection is established and no error - occurs. + occurs. - @sa WaitOnConnect(), wxSocketBase::SetNotify, - wxSocketBase::Notify + @see WaitOnConnect(), wxSocketBase::SetNotify, + wxSocketBase::Notify */ - bool Connect(wxSockAddress& address, bool wait = @true); + bool Connect(wxSockAddress& address, bool wait = true); bool Connect(wxSockAddress& address, wxSockAddress& local, - bool wait = @true); + bool wait = true); //@} /** @@ -298,19 +285,17 @@ public: to Connect() with @e wait set to @false. @param seconds - Number of seconds to wait. - If -1, it will wait for the default timeout, - as set with SetTimeout. - + Number of seconds to wait. + If -1, it will wait for the default timeout, + as set with SetTimeout. @param millisecond - Number of milliseconds to wait. + Number of milliseconds to wait. @returns WaitOnConnect returns @true if the connection request completes. - This does not necessarily mean that the connection - was successfully established; it might also happen - that the connection was refused by the peer. Use - IsConnected to distinguish between these two - situations. + This does not necessarily mean that the connection was + successfully established; it might also happen that the + connection was refused by the peer. Use IsConnected to + distinguish between these two situations. */ bool WaitOnConnect(long seconds = -1, long milliseconds = 0); }; @@ -377,13 +362,13 @@ public: Gets the client data of the socket which generated this event, as set with wxSocketBase::SetClientData. */ - void * GetClientData(); + void* GetClientData(); /** Returns the socket object to which this event refers to. This makes it possible to use the same event handler for different sockets. */ - wxSocketBase * GetSocket(); + wxSocketBase* GetSocket(); /** Returns the socket event type. @@ -434,7 +419,6 @@ public: /** Functions that perform basic IO functionality. - Close() Discard() @@ -450,9 +434,7 @@ public: Write() WriteMsg() - Functions that perform a timed wait on a certain IO condition. - InterruptWait() Wait() @@ -462,14 +444,12 @@ public: WaitForRead() WaitForWrite() - and also: + and also: wxSocketServer::WaitForAccept wxSocketClient::WaitOnConnect - Functions that allow applications to customize socket IO as needed. - GetFlags() SetFlags() @@ -506,7 +486,6 @@ public: the wxSocket to a list of object to be deleted on idle time, after all events have been processed. For the same reason, you should avoid creating socket objects in the stack. - Destroy calls Close() automatically. @returns Always @true. @@ -516,16 +495,13 @@ public: /** This function simply deletes all bytes in the incoming queue. This function always returns immediately and its operation is not affected by IO flags. - Use LastCount() to verify the number of bytes actually discarded. - If you use Error(), it will always return @false. */ wxSocketBase Discard(); /** Returns @true if an error occurred in the last IO operation. - Use this function to check for an error condition after one of the following calls: Discard, Peek, Read, ReadMsg, Unread, Write, WriteMsg. */ @@ -535,7 +511,7 @@ public: Returns a pointer of the client data for this socket, as set with SetClientData() */ - void * GetClientData(); + void* GetClientData(); /** Returns current IO flags, as set with SetFlags() @@ -562,7 +538,6 @@ public: /** Functions that allow applications to receive socket events. - Notify() SetNotify() @@ -583,7 +558,6 @@ public: some exception or abnormal problem. InterruptWait is automatically called when you Close() a socket (and thus also upon socket destruction), so you don't need to use it in these cases. - Wait(), wxSocketServer::WaitForAccept, WaitForLost(), @@ -616,11 +590,10 @@ public: Returns @true if the socket is initialized and ready and @false in other cases. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** Returns the number of bytes read or written by the last IO call. - Use this function to get the number of bytes actually transferred after using one of the following IO calls: Discard, Peek, Read, ReadMsg, Unread, Write, WriteMsg. @@ -630,7 +603,6 @@ public: /** Returns the last wxSocket error. See @ref overview_wxsocketbase "wxSocket errors". - Please note that this function merely returns the last error code, but it should not be used to determine if an error has occurred (this is because successful operations do not change the LastError value). @@ -641,85 +613,75 @@ public: wxSocketError LastError(); /** - According to the @e notify value, this function enables - or disables socket events. If @e notify is @true, the events + According to the @a notify value, this function enables + or disables socket events. If @a notify is @true, the events configured with SetNotify() will - be sent to the application. If @e notify is @false; no events + be sent to the application. If @a notify is @false; no events will be sent. */ void Notify(bool notify); /** - This function peeks a buffer of @e nbytes bytes from the socket. + This function peeks a buffer of @a nbytes bytes from the socket. Peeking a buffer doesn't delete it from the socket input queue. - Use LastCount() to verify the number of bytes actually peeked. - Use Error() to determine if the operation succeeded. @param buffer - Buffer where to put peeked data. - + Buffer where to put peeked data. @param nbytes - Number of bytes. + Number of bytes. @returns Returns a reference to the current object. - @sa Error(), LastError(), LastCount(), - SetFlags() + @see Error(), LastError(), LastCount(), + SetFlags() */ - wxSocketBase Peek(void * buffer, wxUint32 nbytes); + wxSocketBase Peek(void* buffer, wxUint32 nbytes); /** - This function reads a buffer of @e nbytes bytes from the socket. - + This function reads a buffer of @a nbytes bytes from the socket. Use LastCount() to verify the number of bytes actually read. - Use Error() to determine if the operation succeeded. @param buffer - Buffer where to put read data. - + Buffer where to put read data. @param nbytes - Number of bytes. + Number of bytes. @returns Returns a reference to the current object. - @sa Error(), LastError(), LastCount(), - SetFlags() + @see Error(), LastError(), LastCount(), + SetFlags() */ - wxSocketBase Read(void * buffer, wxUint32 nbytes); + wxSocketBase Read(void* buffer, wxUint32 nbytes); /** This function reads a buffer sent by WriteMsg() on a socket. If the buffer passed to the function isn't big enough, the remaining bytes will be discarded. This function always waits for the buffer to be entirely filled, unless an error occurs. - Use LastCount() to verify the number of bytes actually read. - Use Error() to determine if the operation succeeded. @param buffer - Buffer where to put read data. - + Buffer where to put read data. @param nbytes - Size of the buffer. + Size of the buffer. @returns Returns a reference to the current object. - @sa Error(), LastError(), LastCount(), - SetFlags(), WriteMsg() + @see Error(), LastError(), LastCount(), + SetFlags(), WriteMsg() */ - wxSocketBase ReadMsg(void * buffer, wxUint32 nbytes); + wxSocketBase ReadMsg(void* buffer, wxUint32 nbytes); /** This function restores the previous state of the socket, as saved with SaveState() - Calls to SaveState and RestoreState can be nested. - @sa SaveState() + @see SaveState() */ void RestoreState(); @@ -729,10 +691,9 @@ public: event mask, as set with SetNotify() and Notify(), user data, as set with SetClientData(). - Calls to SaveState and RestoreState can be nested. - @sa RestoreState() + @see RestoreState() */ void SaveState(); @@ -741,7 +702,7 @@ public: contain a pointer to this data, which can be retrieved with the wxSocketEvent::GetClientData function. */ - void SetClientData(void * data); + void SetClientData(void* data); /** Sets an event handler to be called when a socket event occurs. The @@ -750,66 +711,55 @@ public: Notify(). @param handler - Specifies the event handler you want to use. - + Specifies the event handler you want to use. @param id - The id of socket event. + The id of socket event. - @sa SetNotify(), Notify(), wxSocketEvent, wxEvtHandler + @see SetNotify(), Notify(), wxSocketEvent, wxEvtHandler */ void SetEventHandler(wxEvtHandler& handler, int id = -1); /** Use SetFlags to customize IO operation for this socket. - The @e flags parameter may be a combination of flags ORed together. + The @a flags parameter may be a combination of flags ORed together. The following flags can be used: - @b wxSOCKET_NONE - Normal functionality. @b wxSOCKET_NOWAIT - Read/write as much data as possible and return immediately. @b wxSOCKET_WAITALL - Wait for all required data to be read/written unless an error occurs. @b wxSOCKET_BLOCK - Block the GUI (do not yield) while reading/writing data. @b wxSOCKET_REUSEADDR - Allows the use of an in-use port (wxServerSocket only) @b wxSOCKET_BROADCAST - Switches the socket to broadcast mode @b wxSOCKET_NOBIND - Stops the socket from being bound to a specific adapter (normally used in conjunction with @b wxSOCKET_BROADCAST) A brief overview on how to use these flags follows. - If no flag is specified (this is the same as @b wxSOCKET_NONE), IO calls will return after some data has been read or written, even when the transfer might not be complete. This is the same as issuing exactly one blocking low-level call to recv() or send(). Note that @e blocking here refers to when the function returns, not to whether the GUI blocks during this time. - If @b wxSOCKET_NOWAIT is specified, IO calls will return immediately. Read operations will retrieve only available data. Write operations will write as much data as possible, depending on how much space is available @@ -817,7 +767,6 @@ public: low-level call to recv() or send(). Note that @e nonblocking here refers to when the function returns, not to whether the GUI blocks during this time. - If @b wxSOCKET_WAITALL is specified, IO calls won't return until ALL the data has been read or written (or until an error occurs), blocking if necessary, and issuing several low level calls if necessary. This is the @@ -825,13 +774,11 @@ public: recv() or send() as needed so as to transfer all the data. Note that @e blocking here refers to when the function returns, not to whether the GUI blocks during this time. - The @b wxSOCKET_BLOCK flag controls whether the GUI blocks during IO operations. If this flag is specified, the socket will not yield during IO calls, so the GUI will remain blocked until the operation completes. If it is not used, then the application must take extra care to avoid unwanted reentrance. - The @b wxSOCKET_REUSEADDR flag controls the use of the SO_REUSEADDR standard setsockopt() flag. This flag allows the socket to bind to a port that is already in use. @@ -848,25 +795,18 @@ public: use of wxSOCKET_REUSEADDR implies SO_REUSEPORT in addition to SO_REUSEADDR to be consistent with Windows. - The @b wxSOCKET_BROADCAST flag controls the use of the SO_BROADCAST standard setsockopt() flag. This flag allows the socket to use the broadcast address, and is generally used in conjunction with @b wxSOCKET_NOBIND and wxIPaddress::BroadcastAddress. - So: - @b wxSOCKET_NONE will try to read at least SOME data, no matter how much. - @b wxSOCKET_NOWAIT will always return immediately, even if it cannot read or write ANY data. - @b wxSOCKET_WAITALL will only return when it has read or written ALL the data. - @b wxSOCKET_BLOCK has nothing to do with the previous flags and it controls whether the GUI blocks. - @b wxSOCKET_REUSEADDR controls special platform-specific behavior for reusing local addresses/ports. */ @@ -882,34 +822,29 @@ public: /** SetNotify specifies which socket events are to be sent to the event handler. - The @e flags parameter may be combination of flags ORed together. The + The @a flags parameter may be combination of flags ORed together. The following flags can be used: - @b wxSOCKET_INPUT_FLAG - to receive wxSOCKET_INPUT @b wxSOCKET_OUTPUT_FLAG - to receive wxSOCKET_OUTPUT @b wxSOCKET_CONNECTION_FLAG - to receive wxSOCKET_CONNECTION @b wxSOCKET_LOST_FLAG - to receive wxSOCKET_LOST For example: + In this example, the user will be notified about incoming socket data and whenever the connection is closed. - For more information on socket events see @ref overview_wxsocketbase "wxSocket events". */ @@ -925,7 +860,6 @@ public: /** Functions to retrieve current state and miscellaneous info. - Error() GetLocal() @@ -952,50 +886,44 @@ public: /** This function unreads a buffer. That is, the data in the buffer is put back in the incoming queue. This function is not affected by wxSocket flags. - If you use LastCount(), it will always return @e nbytes. - If you use Error(), it will always return @false. @param buffer - Buffer to be unread. - + Buffer to be unread. @param nbytes - Number of bytes. + Number of bytes. @returns Returns a reference to the current object. - @sa Error(), LastCount(), LastError() + @see Error(), LastCount(), LastError() */ - wxSocketBase Unread(const void * buffer, wxUint32 nbytes); + wxSocketBase Unread(const void* buffer, wxUint32 nbytes); /** This function waits until any of the following conditions is @true: - The socket becomes readable. The socket becomes writable. An ongoing connection request has completed (wxSocketClient only) An incoming connection request has arrived (wxSocketServer only) The connection has been closed. - Note that it is recommended to use the individual Wait functions to wait for the required condition, instead of this one. @param seconds - Number of seconds to wait. - If -1, it will wait for the default timeout, - as set with SetTimeout. - + Number of seconds to wait. + If -1, it will wait for the default timeout, + as set with SetTimeout. @param millisecond - Number of milliseconds to wait. + Number of milliseconds to wait. @returns Returns @true when any of the above conditions is satisfied, - @false if the timeout was reached. + @false if the timeout was reached. - @sa InterruptWait(), wxSocketServer::WaitForAccept, - WaitForLost(), WaitForRead(), - WaitForWrite(), wxSocketClient::WaitOnConnect + @see InterruptWait(), wxSocketServer::WaitForAccept, + WaitForLost(), WaitForRead(), + WaitForWrite(), wxSocketClient::WaitOnConnect */ bool Wait(long seconds = -1, long millisecond = 0); @@ -1004,17 +932,16 @@ public: the peer gracefully closes the connection or if the connection breaks. @param seconds - Number of seconds to wait. - If -1, it will wait for the default timeout, - as set with SetTimeout. - + Number of seconds to wait. + If -1, it will wait for the default timeout, + as set with SetTimeout. @param millisecond - Number of milliseconds to wait. + Number of milliseconds to wait. @returns Returns @true if the connection was lost, @false if the timeout - was reached. + was reached. - @sa InterruptWait(), Wait() + @see InterruptWait(), Wait() */ bool Wait(long seconds = -1, long millisecond = 0); @@ -1026,16 +953,15 @@ public: is set, in which case the operation might still block). @param seconds - Number of seconds to wait. - If -1, it will wait for the default timeout, - as set with SetTimeout. - + Number of seconds to wait. + If -1, it will wait for the default timeout, + as set with SetTimeout. @param millisecond - Number of milliseconds to wait. + Number of milliseconds to wait. @returns Returns @true if the socket becomes readable, @false on timeout. - @sa InterruptWait(), Wait() + @see InterruptWait(), Wait() */ bool WaitForRead(long seconds = -1, long millisecond = 0); @@ -1047,59 +973,52 @@ public: in which case the operation might still block). @param seconds - Number of seconds to wait. - If -1, it will wait for the default timeout, - as set with SetTimeout. - + Number of seconds to wait. + If -1, it will wait for the default timeout, + as set with SetTimeout. @param millisecond - Number of milliseconds to wait. + Number of milliseconds to wait. @returns Returns @true if the socket becomes writable, @false on timeout. - @sa InterruptWait(), Wait() + @see InterruptWait(), Wait() */ bool WaitForWrite(long seconds = -1, long millisecond = 0); /** - This function writes a buffer of @e nbytes bytes to the socket. - + This function writes a buffer of @a nbytes bytes to the socket. Use LastCount() to verify the number of bytes actually written. - Use Error() to determine if the operation succeeded. @param buffer - Buffer with the data to be sent. - + Buffer with the data to be sent. @param nbytes - Number of bytes. + Number of bytes. @returns Returns a reference to the current object. - @sa Error(), LastError(), LastCount(), - SetFlags() + @see Error(), LastError(), LastCount(), + SetFlags() */ - wxSocketBase Write(const void * buffer, wxUint32 nbytes); + wxSocketBase Write(const void* buffer, wxUint32 nbytes); /** - This function writes a buffer of @e nbytes bytes from the socket, but it + This function writes a buffer of @a nbytes bytes from the socket, but it writes a short header before so that ReadMsg() knows how much data should it actually read. So, a buffer sent with WriteMsg @b must be read with ReadMsg. This function always waits for the entire buffer to be sent, unless an error occurs. - Use LastCount() to verify the number of bytes actually written. - Use Error() to determine if the operation succeeded. @param buffer - Buffer with the data to be sent. - + Buffer with the data to be sent. @param nbytes - Number of bytes to send. + Number of bytes to send. @returns Returns a reference to the current object. */ - wxSocketBase WriteMsg(const void * buffer, wxUint32 nbytes); + wxSocketBase WriteMsg(const void* buffer, wxUint32 nbytes); }; @@ -1122,7 +1041,7 @@ public: Constructor. @param flags - Socket flags (See wxSocketBase::SetFlags) + Socket flags (See wxSocketBase::SetFlags) */ wxDatagramSocket(wxSocketFlags flags = wxSOCKET_NONE); @@ -1132,51 +1051,43 @@ public: ~wxDatagramSocket(); /** - This function reads a buffer of @e nbytes bytes from the socket. - + This function reads a buffer of @a nbytes bytes from the socket. Use wxSocketBase::LastCount to verify the number of bytes actually read. - Use wxSocketBase::Error to determine if the operation succeeded. @param address - Any address - will be overwritten with the address of the peer that sent that - data. - + Any address - will be overwritten with the address of the peer that sent + that data. @param buffer - Buffer where to put read data. - + Buffer where to put read data. @param nbytes - Number of bytes. + Number of bytes. @returns Returns a reference to the current object, and the address of - the peer that sent the data on address param. + the peer that sent the data on address param. - @sa wxSocketBase::Error, wxSocketBase::LastError, wxSocketBase::LastCount, - wxSocketBase::SetFlags, + @see wxSocketBase::Error, wxSocketBase::LastError, wxSocketBase::LastCount, + wxSocketBase::SetFlags, */ wxDatagramSocket ReceiveFrom(wxSockAddress& address, - void * buffer, + void* buffer, wxUint32 nbytes); /** - This function writes a buffer of @e nbytes bytes to the socket. - + This function writes a buffer of @a nbytes bytes to the socket. Use wxSocketBase::LastCount to verify the number of bytes actually wrote. - Use wxSocketBase::Error to determine if the operation succeeded. @param address - The address of the destination peer for this data. - + The address of the destination peer for this data. @param buffer - Buffer where read data is. - + Buffer where read data is. @param nbytes - Number of bytes. + Number of bytes. @returns Returns a reference to the current object. */ wxDatagramSocket SendTo(const wxSockAddress& address, - const void * buffer, + const void* buffer, wxUint32 nbytes); }; diff --git a/interface/sound.h b/interface/sound.h index 550096bf9a..1a247877f1 100644 --- a/interface/sound.h +++ b/interface/sound.h @@ -29,13 +29,12 @@ public: succeeded. @param fileName - The filename or Windows resource. - + The filename or Windows resource. @param isResource - @true if fileName is a resource, @false if it is a filename. + @true if fileName is a resource, @false if it is a filename. */ wxSound(); - wxSound(const wxString& fileName, bool isResource = @false); + wxSound(const wxString& fileName, bool isResource = false); //@} /** @@ -47,24 +46,22 @@ public: Constructs a wave object from a file or resource. @param fileName - The filename or Windows resource. - + The filename or Windows resource. @param isResource - @true if fileName is a resource, @false if it is a filename. + @true if fileName is a resource, @false if it is a filename. @returns @true if the call was successful, @false otherwise. */ - bool Create(const wxString& fileName, bool isResource = @false); + bool Create(const wxString& fileName, bool isResource = false); /** Returns @true if the object contains a successfully loaded file or resource, @false otherwise. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** Returns @true if a sound is played at the moment. - This method is currently not implemented under Windows. */ static bool IsPlaying(); @@ -77,24 +74,20 @@ public: to delete the object which is being asynchronously played any time after calling this function and the sound would continue playing, however this currently doesn't work under Windows for sound objects loaded from memory data. - - The possible values for @e flags are: + The possible values for @a flags are: wxSOUND_SYNC - @c Play will block and wait until the sound is replayed. wxSOUND_ASYNC - Sound is played asynchronously, @c Play returns immediately wxSOUND_ASYNC | wxSOUND_LOOP - Sound is played asynchronously and loops until another sound is played, Stop() is called or the program terminates. diff --git a/interface/spinbutt.h b/interface/spinbutt.h index e5f83aed88..9f532fb2bd 100644 --- a/interface/spinbutt.h +++ b/interface/spinbutt.h @@ -25,7 +25,7 @@ public: /** The constructor is not normally used by the user code. */ - wxSpinEvent(wxEventType commandType = wxEVT_@NULL, int id = 0); + wxSpinEvent(wxEventType commandType = wxEVT_NULL, int id = 0); /** Retrieve the current spin button or control value. @@ -81,26 +81,21 @@ public: Constructor, creating and showing a spin button. @param parent - Parent window. Must not be @NULL. - + Parent window. Must not be @NULL. @param id - Window identifier. The value wxID_ANY indicates a default value. - + Window identifier. The value wxID_ANY indicates a default value. @param pos - Window position. If wxDefaultPosition is specified then a default position - is chosen. - + Window position. If 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 wxDefaultSize is specified then a default size + is chosen. @param style - Window style. See wxSpinButton. - + Window style. See wxSpinButton. @param name - Window name. + Window name. - @sa Create() + @see Create() */ wxSpinButton(); wxSpinButton(wxWindow* parent, wxWindowID id, @@ -128,21 +123,21 @@ public: /** Returns the maximum permissible value. - @sa SetRange() + @see SetRange() */ int GetMax(); /** Returns the minimum permissible value. - @sa SetRange() + @see SetRange() */ int GetMin(); /** Returns the current spin button value. - @sa SetValue() + @see SetValue() */ int GetValue(); @@ -150,12 +145,11 @@ public: Sets the range of the spin button. @param min - The minimum value for the spin button. - + The minimum value for the spin button. @param max - The maximum value for the spin button. + The maximum value for the spin button. - @sa GetMin(), GetMax() + @see GetMin(), GetMax() */ void SetRange(int min, int max); @@ -163,7 +157,7 @@ public: Sets the value of the spin button. @param value - The value for the spin button. + The value for the spin button. */ void SetValue(int value); }; diff --git a/interface/spinctrl.h b/interface/spinctrl.h index e4b068516d..114faeefb8 100644 --- a/interface/spinctrl.h +++ b/interface/spinctrl.h @@ -25,8 +25,7 @@ @appearance{spinctrl.png} @seealso - @ref overview_eventhandlingoverview "Event handling overview", wxSpinButton, - wxControl + @ref overview_eventhandlingoverview, wxSpinButton, wxControl */ class wxSpinCtrl : public wxControl { @@ -34,42 +33,32 @@ public: //@{ /** ) - Constructor, creating and showing a spin control. @param parent - Parent window. Must not be @NULL. - + Parent window. Must not be @NULL. @param value - Default value. - + Default value. @param id - Window identifier. The value wxID_ANY indicates a default value. - + Window identifier. The value wxID_ANY indicates a default value. @param pos - Window position. If wxDefaultPosition is specified then a default position - is chosen. - + Window position. If 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 wxDefaultSize is specified then a default size + is chosen. @param style - Window style. See wxSpinButton. - + Window style. See wxSpinButton. @param min - Minimal value. - + Minimal value. @param max - Maximal value. - + Maximal value. @param initial - Initial value. - + Initial value. @param name - Window name. + Window name. - @sa Create() + @see Create() */ wxSpinCtrl(); wxSpinCtrl(wxWindow* parent, wxWindowID id = -1, @@ -83,9 +72,7 @@ public: /** ) - Creation function called by the spin control constructor. - See wxSpinCtrl() for details. */ bool Create(wxWindow* parent, wxWindowID id = -1, @@ -118,9 +105,8 @@ public: /** Select the text in the text part of the control between positions - @e from (inclusive) and @e to (exclusive). This is similar to + @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 of the control. */ diff --git a/interface/splash.h b/interface/splash.h index 57df843ad2..3bf0360243 100644 --- a/interface/splash.h +++ b/interface/splash.h @@ -40,16 +40,13 @@ public: Construct the splash screen passing a bitmap, a style, a timeout, a window id, optional position and size, and a window style. - - @e splashStyle is a bitlist of some of the following: - + @a splashStyle is a bitlist of some of the following: wxSPLASH_CENTRE_ON_PARENT wxSPLASH_CENTRE_ON_SCREEN wxSPLASH_NO_CENTRE wxSPLASH_TIMEOUT wxSPLASH_NO_TIMEOUT - - @e milliseconds is the timeout in milliseconds. + @a milliseconds is the timeout in milliseconds. */ wxSplashScreen(const wxBitmap& bitmap, long splashStyle, int milliseconds, diff --git a/interface/splitter.h b/interface/splitter.h index 2bf69e0f27..8a0fa9e393 100644 --- a/interface/splitter.h +++ b/interface/splitter.h @@ -52,38 +52,33 @@ public: Constructor for creating the window. @param parent - The parent of the splitter window. - + The parent of the splitter window. @param id - The window identifier. - + The window identifier. @param pos - The window position. - + The window position. @param size - The window size. - + The window size. @param style - The window style. See wxSplitterWindow. - + The window style. See wxSplitterWindow. @param name - The window name. + The window name. @remarks After using this constructor, you must create either one or two - subwindows with the splitter window as parent, and - then call one of Initialize(), - SplitVertically() and - SplitHorizontally() in order to set - the pane(s). - - @sa Initialize(), SplitVertically(), - SplitHorizontally(), Create() + subwindows with the splitter window as parent, and then + call one of Initialize(), + SplitVertically() and + SplitHorizontally() in order to set the + pane(s). + + @see Initialize(), SplitVertically(), + SplitHorizontally(), Create() */ wxSplitterWindow(); wxSplitterWindow(wxWindow* parent, wxWindowID id, const wxPoint& point = wxDefaultPosition, const wxSize& size = wxDefaultSize, - long style=wxSP_3D, + long style = wxSP_3D, const wxString& name = "splitterWindow"); //@} @@ -99,35 +94,35 @@ public: bool Create(wxWindow* parent, wxWindowID id, const wxPoint& point = wxDefaultPosition, const wxSize& size = wxDefaultSize, - long style=wxSP_3D, + long style = wxSP_3D, const wxString& name = "splitterWindow"); /** Returns the current minimum pane size (defaults to zero). - @sa SetMinimumPaneSize() + @see SetMinimumPaneSize() */ int GetMinimumPaneSize(); /** Returns the current sash gravity. - @sa SetSashGravity() + @see SetSashGravity() */ double GetSashGravity(); /** Returns the current sash position. - @sa SetSashPosition() + @see SetSashPosition() */ int GetSashPosition(); /** Gets the split mode. - @sa SetSplitMode(), SplitVertically(), - SplitHorizontally(). + @see SetSplitMode(), SplitVertically(), + SplitHorizontally(). */ int GetSplitMode(); @@ -146,12 +141,12 @@ public: shown if it is currently hidden. @param window - The pane for the unsplit window. + The pane for the unsplit window. @remarks This should be called if you wish to initially view only a - single pane in the splitter window. + single pane in the splitter window. - @sa SplitVertically(), SplitHorizontally() + @see SplitVertically(), SplitHorizontally() */ void Initialize(wxWindow* window); @@ -165,15 +160,14 @@ public: the left mouse button. @param x - The x position of the mouse cursor. - + The x position of the mouse cursor. @param y - The y position of the mouse cursor. + The y position of the mouse cursor. @remarks The default implementation of this function calls Unsplit if the - minimum pane size is zero. + minimum pane size is zero. - @sa Unsplit() + @see Unsplit() */ virtual void OnDoubleClickSash(int x, int y); @@ -182,11 +176,11 @@ public: user. It may return @false to prevent the change or @true to allow it. @param newSashPosition - The new sash position (always positive or zero) + The new sash position (always positive or zero) @remarks The default implementation of this function verifies that the - sizes of both panes of the splitter are greater than - minimum pane size. + sizes of both panes of the splitter are greater than + minimum pane size. */ virtual bool OnSashPositionChange(int newSashPosition); @@ -195,10 +189,10 @@ public: programmatically or using the wxSplitterWindow user interface. @param removed - The window being removed. + The window being removed. @remarks The default implementation of this function simply hides - removed. You may wish to delete the window. + removed. You may wish to delete the window. */ virtual void OnUnsplit(wxWindow* removed); @@ -208,33 +202,31 @@ public: and then resplitting the window back because it will provoke much less flicker (if any). It is valid to call this function whether the splitter has two windows or only one. - - Both parameters should be non-@NULL and @e winOld must specify one of the + Both parameters should be non-@NULL and @a winOld must specify one of the windows managed by the splitter. If the parameters are incorrect or the window couldn't be replaced, @false is returned. Otherwise the function will return @true, but please notice that it will not delete the replaced window and you may wish to do it yourself. - @sa GetMinimumPaneSize() + @see GetMinimumPaneSize() */ - bool ReplaceWindow(wxWindow * winOld, wxWindow * winNew); + bool ReplaceWindow(wxWindow* winOld, wxWindow* winNew); /** Sets the minimum pane size. @param paneSize - Minimum pane size in pixels. + Minimum pane size in pixels. @remarks The default minimum pane size is zero, which means that either - pane can be reduced to zero by dragging the sash, - thus removing one of the panes. To prevent this - behaviour (and veto out-of-range sash dragging), set - a minimum size, for example 20 pixels. If the - wxSP_PERMIT_UNSPLIT style is used when a splitter - window is created, the window may be unsplit even if - minimum size is non-zero. - - @sa GetMinimumPaneSize() + pane can be reduced to zero by dragging the sash, thus + removing one of the panes. To prevent this behaviour + (and veto out-of-range sash dragging), set a minimum + size, for example 20 pixels. If the wxSP_PERMIT_UNSPLIT + style is used when a splitter window is created, the + window may be unsplit even if minimum size is non-zero. + + @see GetMinimumPaneSize() */ void SetMinimumPaneSize(int paneSize); @@ -242,9 +234,9 @@ public: Sets the sash gravity. @param gravity - The sash gravity. Value between 0.0 and 1.0. + The sash gravity. Value between 0.0 and 1.0. - @sa GetSashGravity() + @see GetSashGravity() */ void SetSashGravity(double gravity); @@ -252,22 +244,21 @@ public: Sets the sash position. @param position - The sash position in pixels. - + The sash position in pixels. @param redraw - If @true, resizes the panes and redraws the sash and border. + If @true, resizes the panes and redraws the sash and border. @remarks Does not currently check for an out-of-range value. - @sa GetSashPosition() + @see GetSashPosition() */ - void SetSashPosition(int position, const bool redraw = @true); + void SetSashPosition(int position, const bool redraw = true); /** Sets the sash size. Normally, the sash size is determined according to the metrics of each platform, but the application can override this, for example to show - a thin sash that the user is not expected to drag. If @e size is more -1, + a thin sash that the user is not expected to drag. If @a size is more -1, the custom sash size will be used. */ void SetSashSize(int size); @@ -276,12 +267,12 @@ public: Sets the split mode. @param mode - Can be wxSPLIT_VERTICAL or wxSPLIT_HORIZONTAL. + Can be wxSPLIT_VERTICAL or wxSPLIT_HORIZONTAL. @remarks Only sets the internal variable; does not update the display. - @sa GetSplitMode(), SplitVertically(), - SplitHorizontally(). + @see GetSplitMode(), SplitVertically(), + SplitHorizontally(). */ void SetSplitMode(int mode); @@ -290,27 +281,26 @@ public: child windows are shown if they are currently hidden. @param window1 - The top pane. - + The top pane. @param window2 - The bottom pane. - + The bottom pane. @param sashPosition - The initial position of the sash. If this value is - positive, it specifies the size of the upper pane. If it is negative, its - absolute value gives the size of the lower pane. Finally, specify 0 (default) - to choose the default position (half of the total window height). + The initial position of the sash. If this value is + positive, it specifies the size of the upper pane. If it is negative, its + absolute value gives the size of the lower pane. Finally, specify 0 + (default) + to choose the default position (half of the total window height). @returns @true if successful, @false otherwise (the window was already - split). + split). @remarks This should be called if you wish to initially view two panes. - It can also be called at any subsequent time, but the - application should check that the window is not - currently split using IsSplit. + It can also be called at any subsequent time, but the + application should check that the window is not + currently split using IsSplit. - @sa SplitVertically(), IsSplit(), - Unsplit() + @see SplitVertically(), IsSplit(), + Unsplit() */ bool SplitHorizontally(wxWindow* window1, wxWindow* window2, int sashPosition = 0); @@ -320,27 +310,26 @@ public: child windows are shown if they are currently hidden. @param window1 - The left pane. - + The left pane. @param window2 - The right pane. - + The right pane. @param sashPosition - The initial position of the sash. If this value is - positive, it specifies the size of the left pane. If it is negative, it is - absolute value gives the size of the right pane. Finally, specify 0 (default) - to choose the default position (half of the total window width). + The initial position of the sash. If this value is + positive, it specifies the size of the left pane. If it is negative, it is + absolute value gives the size of the right pane. Finally, specify 0 + (default) + to choose the default position (half of the total window width). @returns @true if successful, @false otherwise (the window was already - split). + split). @remarks This should be called if you wish to initially view two panes. - It can also be called at any subsequent time, but the - application should check that the window is not - currently split using IsSplit. + It can also be called at any subsequent time, but the + application should check that the window is not + currently split using IsSplit. - @sa SplitHorizontally(), IsSplit(), - Unsplit(). + @see SplitHorizontally(), IsSplit(), + Unsplit(). */ bool SplitVertically(wxWindow* window1, wxWindow* window2, int sashPosition = 0); @@ -349,24 +338,22 @@ public: Unsplits the window. @param toRemove - The pane to remove, or @NULL to remove the right or bottom pane. + The pane to remove, or @NULL to remove the right or bottom pane. @returns @true if successful, @false otherwise (the window was not split). @remarks This call will not actually delete the pane being removed; it - calls OnUnsplit which can be overridden for the - desired behaviour. By default, the pane being removed - is hidden. + calls OnUnsplit which can be overridden for the desired + behaviour. By default, the pane being removed is hidden. - @sa SplitHorizontally(), SplitVertically(), - IsSplit(), OnUnsplit() + @see SplitHorizontally(), SplitVertically(), + IsSplit(), OnUnsplit() */ - bool Unsplit(wxWindow* toRemove = @NULL); + bool Unsplit(wxWindow* toRemove = NULL); /** Causes any pending sizing of the sash and child panes to take place immediately. - Such resizing normally takes place in idle time, in order to wait for layout to be completed. However, this can cause unacceptable flicker as the panes are resized after the window has been @@ -393,7 +380,7 @@ public: @category{events} @seealso - wxSplitterWindow, @ref overview_eventhandlingoverview "Event handling overview" + wxSplitterWindow, @ref overview_eventhandlingoverview */ class wxSplitterEvent : public wxNotifyEvent { @@ -401,12 +388,11 @@ public: /** Constructor. Used internally by wxWidgets only. */ - wxSplitterEvent(wxEventType eventType = wxEVT_@NULL, - wxSplitterWindow * splitter = @NULL); + wxSplitterEvent(wxEventType eventType = wxEVT_NULL, + wxSplitterWindow* splitter = NULL); /** Returns the new sash position. - May only be called while processing wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING and wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events. @@ -416,7 +402,6 @@ public: /** Returns a pointer to the window being removed when a splitter window is unsplit. - May only be called while processing wxEVT_COMMAND_SPLITTER_UNSPLIT events. */ @@ -424,19 +409,17 @@ public: /** Returns the x coordinate of the double-click point. - May only be called while processing wxEVT_COMMAND_SPLITTER_DOUBLECLICKED events. */ -#define int GetX() /* implementation is private */ + int GetX(); /** Returns the y coordinate of the double-click point. - May only be called while processing wxEVT_COMMAND_SPLITTER_DOUBLECLICKED events. */ -#define int GetY() /* implementation is private */ + int GetY(); /** In the case of wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events, @@ -445,13 +428,12 @@ public: tracking bar position so visual feedback during dragging will represent that change that will actually take place. Set to -1 from the event handler code to prevent repositioning. - May only be called while processing wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING and wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events. @param pos - New sash position. + New sash position. */ void SetSashPosition(int pos); }; diff --git a/interface/srchctrl.h b/interface/srchctrl.h index a41c566cf2..9990bd775c 100644 --- a/interface/srchctrl.h +++ b/interface/srchctrl.h @@ -54,30 +54,23 @@ public: Constructor, creating and showing a text control. @param parent - Parent window. Should not be @NULL. - + Parent window. Should not be @NULL. @param id - Control identifier. A value of -1 denotes a default value. - + Control identifier. A value of -1 denotes a default value. @param value - Default text value. - + Default text value. @param pos - Text control position. - + Text control position. @param size - Text control size. - + Text control size. @param style - Window style. See wxSearchCtrl. - + Window style. See wxSearchCtrl. @param validator - Window validator. - + Window validator. @param name - Window name. + Window name. - @sa wxTextCtrl::Create, wxValidator + @see wxTextCtrl::Create, wxValidator */ wxSearchCtrl(); wxSearchCtrl(wxWindow* parent, wxWindowID id, @@ -105,7 +98,6 @@ public: If there is a menu attached, the search button will be visible regardless of the search button visibility value. - This always returns @false in Mac OS X v10.3 */ virtual bool IsSearchButtonVisible(); @@ -116,7 +108,7 @@ public: the search control it is deleted. @param menu - Menu to attach to the search control. + Menu to attach to the search control. */ virtual void SetMenu(wxMenu* menu); @@ -130,7 +122,6 @@ public: If there is a menu attached, the search button will be visible regardless of the search button visibility value. - This has no effect in Mac OS X v10.3 */ virtual void ShowSearchButton(bool show); diff --git a/interface/sstream.h b/interface/sstream.h index 243a420236..a3711cadaa 100644 --- a/interface/sstream.h +++ b/interface/sstream.h @@ -46,14 +46,13 @@ public: If the provided pointer is non-@NULL, data will be written to it. Otherwise, an internal string is used for the data written to this stream, use GetString() to get access to it. - - If @e str is used, data written to the stream is appended to the current + If @a str is used, data written to the stream is appended to the current contents of it, i.e. the string is not cleared here. However if it is not empty, the positions returned by wxOutputStream::TellO will be offset by the initial string length, i.e. initial stream position will be the initial length of the string and not 0. */ - wxStringOutputStream(wxString str = @NULL); + wxStringOutputStream(wxString str = NULL); /** Returns the string containing all the data written to the stream so far. diff --git a/interface/stackwalk.h b/interface/stackwalk.h index 0474f4e2b9..50978638eb 100644 --- a/interface/stackwalk.h +++ b/interface/stackwalk.h @@ -71,8 +71,7 @@ public: number of them (this can be useful when Walk() is called from some known location and you don't want to see the first few frames anyhow; also notice that Walk() frame itself is not included if skip = 1). - - Up to @e maxDepth frames are walked from the innermost to the outermost one. + Up to @a maxDepth frames are walked from the innermost to the outermost one. */ void Walk(size_t skip = 1, size_t maxDepth = 200); @@ -80,8 +79,7 @@ public: Enumerate stack frames from the location of uncaught exception. This method can only be called from wxApp::OnFatalException. - - Up to @e maxDepth frames are walked from the innermost to the outermost one. + Up to @a maxDepth frames are walked from the innermost to the outermost one. */ void WalkFromException(size_t maxDepth = 200); }; @@ -113,7 +111,6 @@ public: /** Return the name of the file containing this frame, empty if unavailable (typically because debug info is missing). - Use HasSourceLocation() to check whether the file name is available. */ @@ -127,7 +124,7 @@ public: /** Return the line number of this frame, 0 if unavailable. - @sa GetFileName() + @see GetFileName() */ size_t GetLine(); @@ -151,14 +148,12 @@ public: Get the name, type and value (in text form) of the given parameter. Any pointer may be @NULL if you're not interested in the corresponding value. - Return @true if at least some values could be retrieved. - This function currently is only implemented under Win32 and requires a PDB file. */ - bool GetParam(size_t n, wxString * type, wxString * name, - wxString * value); + bool GetParam(size_t n, wxString* type, wxString* name, + wxString* value); /** Return the number of parameters of this function (may return 0 if we diff --git a/interface/statbmp.h b/interface/statbmp.h index c5cb6b3bba..9c32646962 100644 --- a/interface/statbmp.h +++ b/interface/statbmp.h @@ -31,27 +31,21 @@ public: Constructor, creating and showing a static bitmap control. @param parent - Parent window. Should not be @NULL. - + Parent window. Should not be @NULL. @param id - Control identifier. A value of -1 denotes a default value. - + Control identifier. A value of -1 denotes a default value. @param label - Bitmap label. - + Bitmap label. @param pos - Window position. - + Window position. @param size - Window size. - + Window size. @param style - Window style. See wxStaticBitmap. - + Window style. See wxStaticBitmap. @param name - Window name. + Window name. - @sa Create() + @see Create() */ wxStaticBitmap(); wxStaticBitmap(wxWindow* parent, wxWindowID id, @@ -76,7 +70,7 @@ public: Returns the bitmap currently used in the control. Notice that this method can be called even if SetIcon() had been used. - @sa SetBitmap() + @see SetBitmap() */ wxBitmap GetBitmap(); @@ -86,7 +80,7 @@ public: can't be retrieved from the control if a bitmap had been set (using wxStaticBitmap::SetBitmap). - @sa SetIcon() + @see SetIcon() */ wxIcon GetIcon(); @@ -94,9 +88,9 @@ public: Sets the bitmap label. @param label - The new bitmap. + The new bitmap. - @sa GetBitmap() + @see GetBitmap() */ virtual void SetBitmap(const wxBitmap& label); @@ -104,7 +98,7 @@ public: Sets the label to the given icon. @param label - The new icon. + The new icon. */ virtual void SetIcon(const wxIcon& label); }; diff --git a/interface/statbox.h b/interface/statbox.h index 5019a1b946..3475a407f8 100644 --- a/interface/statbox.h +++ b/interface/statbox.h @@ -38,28 +38,23 @@ public: Constructor, creating and showing a static box. @param parent - Parent window. Must not be @NULL. - + Parent window. Must not be @NULL. @param id - Window identifier. The value wxID_ANY indicates a default value. - + Window identifier. The value wxID_ANY indicates a default value. @param label - Text to be displayed in the static box, the empty string for no label. - + Text to be displayed in the static box, the empty string for no label. @param pos - Window position. If wxDefaultPosition is specified then a default position - is chosen. - + Window position. If wxDefaultPosition is specified then a default + position is chosen. @param size - Checkbox size. If the size (-1, -1) is specified then a default size is chosen. - + Checkbox size. If the size (-1, -1) is specified then a default size is + chosen. @param style - Window style. See wxStaticBox. - + Window style. See wxStaticBox. @param name - Window name. + Window name. - @sa Create() + @see Create() */ wxStaticBox(); wxStaticBox(wxWindow* parent, wxWindowID id, diff --git a/interface/statline.h b/interface/statline.h index f5304a7e89..084a275ed5 100644 --- a/interface/statline.h +++ b/interface/statline.h @@ -34,26 +34,21 @@ public: Constructor, creating and showing a static line. @param parent - Parent window. Must not be @NULL. - + Parent window. Must not be @NULL. @param id - Window identifier. The value wxID_ANY indicates a default value. - + Window identifier. The value wxID_ANY indicates a default value. @param pos - Window position. If wxDefaultPosition is specified then a default position - is chosen. - + Window position. If wxDefaultPosition is specified then a default + position is chosen. @param size - Size. Note that either the height or the width (depending on - whether the line if horizontal or vertical) is ignored. - + Size. Note that either the height or the width (depending on + whether the line if horizontal or vertical) is ignored. @param style - Window style (either wxLI_HORIZONTAL or wxLI_VERTICAL). - + Window style (either wxLI_HORIZONTAL or wxLI_VERTICAL). @param name - Window name. + Window name. - @sa Create() + @see Create() */ wxStaticLine(); wxStaticLine(wxWindow* parent, wxWindowID id = wxID_ANY, diff --git a/interface/stattext.h b/interface/stattext.h index 3ada9ff828..7c2da1dc22 100644 --- a/interface/stattext.h +++ b/interface/stattext.h @@ -53,27 +53,21 @@ public: Constructor, creating and showing a text control. @param parent - Parent window. Should not be @NULL. - + Parent window. Should not be @NULL. @param id - Control identifier. A value of -1 denotes a default value. - + Control identifier. A value of -1 denotes a default value. @param label - Text label. - + Text label. @param pos - Window position. - + Window position. @param size - Window size. - + Window size. @param style - Window style. See wxStaticText. - + Window style. See wxStaticText. @param name - Window name. + Window name. - @sa Create() + @see Create() */ wxStaticText(); wxStaticText(wxWindow* parent, wxWindowID id, @@ -96,10 +90,8 @@ public: /** Returns the contents of the control. - Note that the returned string contains both the mnemonics (@c characters), if any, and markup tags, if any. - Use GetLabelText() if only the label text is needed. */ @@ -110,8 +102,7 @@ public: The first form returns the control's label without the mnemonics characters (if any) and without the markup (if the control has @c wxST_MARKUP style). - - The second (static) version returns the given @e label string without the + The second (static) version returns the given @a label string without the mnemonics characters (if any) and without the markup. */ @@ -122,117 +113,96 @@ public: /** Sets the static text label and updates the controls size to exactly fit the label unless the control has wxST_NO_AUTORESIZE flag. - This function allows to set decorated static label text on platforms which support it (currently only GTK+ 2). For the other platforms, the markup is ignored. - The supported tags are: - b - bold text big - bigger text i - italic text s - strike-through text sub - subscript text sup - superscript text small - smaller text tt - monospaced text u - underlined text span - generic formatter tag; see Pango Markup for more information. Note that the string must be well-formed (e.g. all tags must be correctly closed) otherwise it can be not shown correctly or at all. - Also note that you need to escape the following special characters: - @b Special character - @b Escape as @c - @c amp; or as @c @c ' - @c apos; @c " - @c quot; @c - @c lt; @c - @c gt; The non-escaped ampersand @c characters are interpreted as mnemonics; see wxControl::SetLabel. + Example: @param label - The new label to set. It may contain newline characters and the markup tags + The new label to set. It may contain newline characters and the markup tags described above. */ virtual void SetLabel(const wxString& label); /** This functions wraps the controls label so that each of its lines becomes at - most @e width pixels wide if possible (the lines are broken at words + most @a width pixels wide if possible (the lines are broken at words boundaries so it might not be the case if words are too long). If @e width is negative, no wrapping is done. - This function is new since wxWidgets version 2.6.2 */ void Wrap(int width); diff --git a/interface/statusbr.h b/interface/statusbr.h index 85ffc2dc76..7519844439 100644 --- a/interface/statusbr.h +++ b/interface/statusbr.h @@ -42,21 +42,19 @@ public: Constructor, creating the window. @param parent - The window parent, usually a frame. - + The window parent, usually a frame. @param id - The window identifier. It may take a value of -1 to indicate a default value. - + The window identifier. It may take a value of -1 to indicate a default + value. @param style - The window style. See wxStatusBar. - + The window style. See wxStatusBar. @param name - The name of the window. This parameter is used to associate a name with the + The name of the window. This parameter is used to associate a name with the item, - allowing the application user to set Motif resource values for - individual windows. + allowing the application user to set Motif resource values for + individual windows. - @sa Create() + @see Create() */ wxStatusBar(); wxStatusBar(wxWindow* parent, wxWindowID id = wxID_ANY, @@ -71,7 +69,6 @@ public: /** Creates the window, for two-step construction. - See wxStatusBar() for details. */ bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, @@ -82,14 +79,13 @@ public: Returns the size and position of a field's internal bounding rectangle. @param i - The field in question. - + The field in question. @param rect - The rectangle values are placed in this variable. + The rectangle values are placed in this variable. @returns @true if the field index is valid, @false otherwise. - @sa wxRect + @see wxRect */ virtual bool GetFieldRect(int i, wxRect& rect); @@ -102,12 +98,12 @@ public: Returns the string associated with a status bar field. @param i - The number of the status field to retrieve, starting from zero. + The number of the status field to retrieve, starting from zero. @returns The status field string if the field is valid, otherwise the - empty string. + empty string. - @sa SetStatusText() + @see SetStatusText() */ virtual wxString GetStatusText(int i = 0); @@ -115,7 +111,7 @@ public: Sets the field text to the top of the stack, and pops the stack of saved strings. - @sa PushStatusText() + @see PushStatusText() */ void PopStatusText(int field = 0); @@ -129,13 +125,12 @@ public: Sets the number of fields, and optionally the field widths. @param number - The number of fields. - + The number of fields. @param widths - An array of n integers interpreted in the same way as - in SetStatusWidths + An array of n integers interpreted in the same way as + in SetStatusWidths */ - virtual void SetFieldsCount(int number = 1, int* widths = @NULL); + virtual void SetFieldsCount(int number = 1, int* widths = NULL); /** Sets the minimal possible height for the status bar. The real height may be @@ -150,42 +145,59 @@ public: or raised instead of the standard sunken 3D border. @param n - The number of fields in the status bar. Must be equal to the - number passed to SetFieldsCount the last - time it was called. - + The number of fields in the status bar. Must be equal to the + number passed to SetFieldsCount the last + time it was called. @param styles - Contains an array of n integers with the styles for each field. There - are three possible styles: + Contains an array of n integers with the styles for each field. There + are three possible styles: + + + + + + + + wxSB_NORMAL + - wxSB_NORMAL + (default) The field appears sunken with a standard 3D border. - (default) The field appears sunken with a standard 3D border. - wxSB_FLAT - No border is painted around the field so that it appears flat. - wxSB_RAISED + wxSB_FLAT - A raised 3D border is painted around the field. + + + No border is painted around the field so that it appears flat. + + + + + + wxSB_RAISED + + + + + A raised 3D border is painted around the field. */ - virtual void SetStatusStyles(int n, int * styles); + virtual void SetStatusStyles(int n, int* styles); /** Sets the text for one field. @param text - The text to be set. Use an empty string ("") to clear the field. - + The text to be set. Use an empty string ("") to clear the field. @param i - The field to set, starting from zero. + The field to set, starting from zero. - @sa GetStatusText(), wxFrame::SetStatusText + @see GetStatusText(), wxFrame::SetStatusText */ virtual void SetStatusText(const wxString& text, int i = 0); @@ -197,27 +209,25 @@ public: the space left for all variable width fields is divided between them according to the absolute value of this number. A variable width field with width of -2 gets twice as much of it as a field with width -1 and so on. - For example, to create one fixed width field of width 100 in the right part of the status bar and two more fields which get 66% and 33% of the remaining space correspondingly, you should use an array containing -2, -1 and 100. @param n - The number of fields in the status bar. Must be equal to the - number passed to SetFieldsCount the last - time it was called. - + The number of fields in the status bar. Must be equal to the + number passed to SetFieldsCount the last + time it was called. @param widths - Contains an array of n integers, each of which is - either an absolute status field width in pixels if positive or indicates a - variable width field if negative. + Contains an array of n integers, each of which is + either an absolute status field width in pixels if positive or indicates a + variable width field if negative. @remarks The widths of the variable fields are calculated from the total - width of all fields, minus the sum of widths of the - non-variable fields, divided by the number of - variable fields. + width of all fields, minus the sum of widths of the + non-variable fields, divided by the number of variable + fields. - @sa SetFieldsCount(), wxFrame::SetStatusWidths + @see SetFieldsCount(), wxFrame::SetStatusWidths */ - virtual void SetStatusWidths(int n, int * widths); + virtual void SetStatusWidths(int n, int* widths); }; diff --git a/interface/stc/stc.h b/interface/stc/stc.h index b1176688e0..0c36146365 100644 --- a/interface/stc/stc.h +++ b/interface/stc/stc.h @@ -141,12 +141,12 @@ public: /** */ -#define int GetX() /* implementation is private */ + int GetX(); /** */ -#define int GetY() /* implementation is private */ + int GetY(); /** @@ -241,12 +241,12 @@ public: /** */ -#define void SetX(int val) /* implementation is private */ + void SetX(int val); /** */ -#define void SetY(int val) /* implementation is private */ + void SetY(int val); }; @@ -283,7 +283,7 @@ public: /** Ctor. */ - wxStyledTextCtrl::wxStyledTextCtrl(wxWindow * parent, + wxStyledTextCtrl::wxStyledTextCtrl(wxWindow* parent, wxWindowID id = wxID_ANY, const wxPoint pos = wxDefaultPosition, const wxSize size = wxDefaultSize, @@ -692,7 +692,7 @@ public: /** Cut the selection to the clipboard. */ -#define void Cut() /* implementation is private */ + void Cut(); /** Delete back from the current position to the start of the line. @@ -901,7 +901,6 @@ public: /** END of generated section - Others... Returns the line number of the line with the caret. */ @@ -2571,7 +2570,7 @@ public: character. If more than one line selected, indent the lines. */ -#define void Tab() /* implementation is private */ + void Tab(); /** Make the target range start and end be the same as the selection range start diff --git a/interface/stdpaths.h b/interface/stdpaths.h index 3769d2a524..6f4940266d 100644 --- a/interface/stdpaths.h +++ b/interface/stdpaths.h @@ -50,53 +50,44 @@ public: /** Returns reference to the unique global standard paths object. */ -#define static wxStandardPathsBase Get() /* implementation is private */ + static wxStandardPathsBase Get(); /** Return the directory containing the system config files. - Example return values: - Unix: @c /etc Windows: @c C:\Documents and Settings\All Users\Application Data Mac: @c /Library/Preferences - @sa wxFileConfig + @see wxFileConfig */ wxString GetConfigDir(); /** Return the location of the applications global, i.e. not user-specific, data files. - Example return values: - Unix: @c @e prefix/share/@e appname Windows: the directory where the executable file is located Mac: @c @e appname.app/Contents/SharedSupport bundle subdirectory - @sa GetLocalDataDir() + @see GetLocalDataDir() */ wxString GetDataDir(); /** Return the directory containing the current user's documents. - Example return values: - Unix: @c ~ (the home directory) Windows: @c C:\Documents and Settings\@e username\Documents Mac: @c ~/Documents - This function is new since wxWidgets version 2.7.0 */ wxString GetDocumentsDir(); /** Return the directory and the filename for the current executable. - Example return values: - Unix: @c /usr/local/bin/exename Windows: @c C:\Programs\AppFolder\exename.exe Mac: @c /Programs/exename @@ -105,10 +96,8 @@ public: /** @b Note: This function is only available under Unix. - Return the program installation prefix, e.g. @c /usr, @c /opt or @c /home/zeitlin. - If the prefix had been previously by SetInstallPrefix(), returns that value, otherwise tries to determine it automatically (Linux only right @@ -119,7 +108,6 @@ public: /** Return the location for application data files which are host-specific and can't, or shouldn't, be shared with the other machines. - This is the same as GetDataDir() except under Unix where it returns @c /etc/@e appname. */ @@ -128,13 +116,11 @@ public: /** Return the localized resources directory containing the resource files of the specified category for the given language. - - In general this is just the same as @e lang subdirectory of + In general this is just the same as @a lang subdirectory of GetResourcesDir() (or @c @e lang.lproj under Mac OS X) but is something quite different for message catalog category under Unix where it returns the standard @c @e prefix/share/locale/@e lang/LC_MESSAGES directory. - This function is new since wxWidgets version 2.7.0 */ wxString GetLocalizedResourcesDir(const wxString& lang, @@ -142,14 +128,12 @@ public: /** Return the directory where the loadable modules (plugins) live. - Example return values: - Unix: @c @e prefix/lib/@e appname Windows: the directory of the executable file Mac: @c @e appname.app/Contents/PlugIns bundle subdirectory - @sa wxDynamicLibrary + @see wxDynamicLibrary */ wxString GetPluginsDir(); @@ -157,19 +141,15 @@ public: Return the directory where the application resource files are located. The resources are the auxiliary data files needed for the application to run and include, for example, image and sound files it might use. - This function is the same as GetDataDir() for all platforms except Mac OS X. - Example return values: - Unix: @c @e prefix/share/@e appname Windows: the directory where the executable file is located Mac: @c @e appname.app/Contents/Resources bundle subdirectory - This function is new since wxWidgets version 2.7.0 - @sa GetLocalizedResourcesDir() + @see GetLocalizedResourcesDir() */ wxString GetResourcesDir(); @@ -178,18 +158,15 @@ public: files, it is best to use wxFileName::CreateTempFileName for correct behaviour when multiple processes are attempting to create temporary files. - This function is new since wxWidgets version 2.7.2 */ wxString GetTempDir(); /** Return the directory for the user config files: - Unix: @c ~ (the home directory) Windows: @c C:\Documents and Settings\@e username\Application Data Mac: @c ~/Library/Preferences - Only use this method if you have a single configuration file to put in this directory, otherwise GetUserDataDir() is more appropriate. @@ -198,7 +175,6 @@ public: /** Return the directory for the user-dependent application data files: - Unix: @c ~/.@e appname Windows: @c C:\Documents and Settings\@e username\Application Data\@e appname @@ -209,7 +185,6 @@ public: /** Return the directory for user data files which shouldn't be shared with the other machines. - This is the same as GetUserDataDir() for all platforms except Windows where it returns @c C:\Documents and Settings\@e username\Local Settings\Application Data\@e @@ -219,11 +194,9 @@ public: /** @b Note: This function is only available under Unix. - Lets wxStandardPaths know about the real program installation prefix on a Unix system. By default, the value returned by GetInstallPrefix() is used. - Although under Linux systems the program prefix may usually be determined automatically, portable programs should call this function. Usually the prefix is set during program configuration if using GNU autotools and so it is enough @@ -235,12 +208,10 @@ public: Controls what application information is used when constructing paths that should be unique to this program, such as the application data directory, the plugins directory on Unix, etc. - - Valid values for @e info are @c AppInfo_None and either one or + Valid values for @a info are @c AppInfo_None and either one or combination of @c AppInfo_AppName and @c AppInfo_VendorName. The first one tells this class to not use neither application nor vendor name in the paths. - By default, only the application name is used under Unix systems but both application and vendor names are used under Windows and Mac. */ diff --git a/interface/stockitem.h b/interface/stockitem.h index c02e77cc66..d61fd0f907 100644 --- a/interface/stockitem.h +++ b/interface/stockitem.h @@ -7,22 +7,20 @@ ///////////////////////////////////////////////////////////////////////////// /** -Returns label that should be used for given @e id element. +Returns label that should be used for given @a id element. @param id -given id of the wxMenuItem, wxButton, wxToolBar tool, etc. - + given id of the wxMenuItem, wxButton, wxToolBar tool, etc. @param withCodes -if @false then strip accelerator code from the label; -useful for getting labels without accelerator char code like for toolbar + if @false then strip accelerator code from the label; + useful for getting labels without accelerator char code like for toolbar tooltip or -on platforms without traditional keyboard like smartphones - + on platforms without traditional keyboard like smartphones @param accelerator -optional accelerator string automatically added to label; useful -for building labels for wxMenuItem + optional accelerator string automatically added to label; useful + for building labels for wxMenuItem */ -wxString wxGetStockLabel(wxWindowID id, bool withCodes = @true, +wxString wxGetStockLabel(wxWindowID id, bool withCodes = true, const wxString& accelerator = wxEmptyString); diff --git a/interface/stopwatch.h b/interface/stopwatch.h index 883c0b5aa8..a94d6add20 100644 --- a/interface/stopwatch.h +++ b/interface/stopwatch.h @@ -42,7 +42,6 @@ public: /** Pauses the stop watch. Call Resume() to resume time measuring again. - If this method is called several times, @c Resume() must be called the same number of times to really resume the stop watch. You may, however, call Start() to resume it unconditionally. @@ -76,21 +75,21 @@ public: /** Returns the number of seconds since local time 00:00:00 Jan 1st 1970. - @sa wxDateTime::Now + @see wxDateTime::Now */ long wxGetLocalTime(); /** Returns the number of seconds since GMT 00:00:00 Jan 1st 1970. - @sa wxDateTime::Now + @see wxDateTime::Now */ long wxGetUTCTime(); /** Returns the number of milliseconds since local time 00:00:00 Jan 1st 1970. - @sa wxDateTime::Now, wxLongLong + @see wxDateTime::Now, wxLongLong */ wxLongLong wxGetLocalTimeMillis(); diff --git a/interface/strconv.h b/interface/strconv.h index a49af87103..53bc4f9a5b 100644 --- a/interface/strconv.h +++ b/interface/strconv.h @@ -28,13 +28,13 @@ public: Converts from UTF-7 encoding to Unicode. Returns the size of the destination buffer. */ -#define size_t MB2WC(wchar_t* buf, const char* psz, size_t n) /* implementation is private */ + size_t MB2WC(wchar_t* buf, const char* psz, size_t n); /** Converts from Unicode to UTF-7 encoding. Returns the size of the destination buffer. */ -#define size_t WC2MB(char* buf, const wchar_t* psz, size_t n) /* implementation is private */ + size_t WC2MB(char* buf, const wchar_t* psz, size_t n); }; @@ -58,13 +58,13 @@ public: Converts from UTF-8 encoding to Unicode. Returns the size of the destination buffer. */ -#define size_t MB2WC(wchar_t* buf, const char* psz, size_t n) /* implementation is private */ + size_t MB2WC(wchar_t* buf, const char* psz, size_t n); /** Converts from Unicode to UTF-8 encoding. Returns the size of the destination buffer. */ -#define size_t WC2MB(char* buf, const wchar_t* psz, size_t n) /* implementation is private */ + size_t WC2MB(char* buf, const wchar_t* psz, size_t n); }; @@ -94,13 +94,13 @@ public: Converts from UTF-16 encoding to Unicode. Returns the size of the destination buffer. */ -#define size_t MB2WC(wchar_t* buf, const char* psz, size_t n) /* implementation is private */ + size_t MB2WC(wchar_t* buf, const char* psz, size_t n); /** Converts from Unicode to UTF-16 encoding. Returns the size of the destination buffer. */ -#define size_t WC2MB(char* buf, const wchar_t* psz, size_t n) /* implementation is private */ + size_t WC2MB(char* buf, const wchar_t* psz, size_t n); }; @@ -140,25 +140,23 @@ public: /** Returns @true if the charset (or the encoding) given at constructor is really available to use. Returns @false if ISO 8859-1 will be used instead. - Note this does not mean that a given string will be correctly converted. A malformed string may still make conversion functions return @c wxCONV_FAILED. - This function is new since wxWidgets version 2.8.2 */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** Converts from the selected character set to Unicode. Returns length of string written to destination buffer. */ -#define size_t MB2WC(wchar_t* buf, const char* psz, size_t n) /* implementation is private */ + size_t MB2WC(wchar_t* buf, const char* psz, size_t n); /** Converts from Unicode to the selected character set. Returns length of string written to destination buffer. */ -#define size_t WC2MB(char* buf, const wchar_t* psz, size_t n) /* implementation is private */ + size_t WC2MB(char* buf, const wchar_t* psz, size_t n); }; @@ -204,13 +202,13 @@ public: Converts from multibyte filename encoding to Unicode. Returns the size of the destination buffer. */ -#define size_t MB2WC(wchar_t* buf, const char* psz, size_t n) /* implementation is private */ + size_t MB2WC(wchar_t* buf, const char* psz, size_t n); /** Converts from Unicode to multibyte filename encoding. Returns the size of the destination buffer. */ -#define size_t WC2MB(char* buf, const wchar_t* psz, size_t n) /* implementation is private */ + size_t WC2MB(char* buf, const wchar_t* psz, size_t n); }; @@ -240,13 +238,13 @@ public: Converts from UTF-32 encoding to Unicode. Returns the size of the destination buffer. */ -#define size_t MB2WC(wchar_t* buf, const char* psz, size_t n) /* implementation is private */ + size_t MB2WC(wchar_t* buf, const char* psz, size_t n); /** Converts from Unicode to UTF-32 encoding. Returns the size of the destination buffer. */ -#define size_t WC2MB(char* buf, const wchar_t* psz, size_t n) /* implementation is private */ + size_t WC2MB(char* buf, const wchar_t* psz, size_t n); }; @@ -285,14 +283,14 @@ public: return a new copy of the object it is called on. It is used for copying the conversion objects while preserving their dynamic type. */ - virtual wxMBConv * Clone(); + virtual wxMBConv* Clone(); /** This function has the same semantics as ToWChar() except that it converts a wide string to multibyte one. */ - virtual size_t FromWChar(char * dst, size_t dstLen, - const wchar_t * src, + virtual size_t FromWChar(char* dst, size_t dstLen, + const wchar_t* src, size_t srcLen = wxNO_LEN); /** @@ -308,7 +306,6 @@ public: Returns the maximal value which can be returned by GetMBNulLen() for any conversion object. Currently this value is 4. - This method can be used to allocate the buffer with enough space for the trailing @c NUL characters for any encoding. */ @@ -316,74 +313,65 @@ public: /** This function is deprecated, please use ToWChar() instead - - Converts from a string @e in in multibyte encoding to Unicode putting up to - @e outLen characters into the buffer @e out. - - If @e out is @NULL, only the length of the string which would result from + Converts from a string @a in in multibyte encoding to Unicode putting up to + @a outLen characters into the buffer @e out. + If @a out is @NULL, only the length of the string which would result from the conversion is calculated and returned. Note that this is the length and not size, i.e. the returned value does not include the trailing @c NUL. But - when the function is called with a non-@NULL @e out buffer, the @e outLen + when the function is called with a non-@NULL @a out buffer, the @a outLen parameter should be one more to allow to properly @c NUL-terminate the string. @param out - The output buffer, may be @NULL if the caller is only - interested in the length of the resulting string - + The output buffer, may be @NULL if the caller is only + interested in the length of the resulting string @param in - The NUL-terminated input string, cannot be @NULL - + The NUL-terminated input string, cannot be @NULL @param outLen - The length of the output buffer but including - NUL, ignored if out is @NULL + The length of the output buffer but including + NUL, ignored if out is @NULL @returns The length of the converted string excluding the trailing NUL. */ -#define virtual size_t MB2WC(wchar_t * out, const char * in, - size_t outLen) /* implementation is private */ + virtual size_t MB2WC(wchar_t* out, const char* in, + size_t outLen); /** The most general function for converting a multibyte string to a wide string. - The main case is when @e dst is not @NULL and @e srcLen is not + The main case is when @a dst is not @NULL and @a srcLen is not @c wxNO_LEN (which is defined as @c (size_t)-1): then - the function converts exactly @e srcLen bytes starting at @e src into + the function converts exactly @a srcLen bytes starting at @a src into wide string which it output to @e dst. If the length of the resulting wide string is greater than @e dstLen, an error is returned. Note that if - @e srcLen bytes don't include @c NUL characters, the resulting wide string is + @a srcLen bytes don't include @c NUL characters, the resulting wide string is not @c NUL-terminated neither. - - If @e srcLen is @c wxNO_LEN, the function supposes that the string is + If @a srcLen is @c wxNO_LEN, the function supposes that the string is properly (i.e. as necessary for the encoding handled by this conversion) @c NUL-terminated and converts the entire string, including any trailing @c NUL bytes. In this case the wide string is also @c NUL-terminated. - - Finally, if @e dst is @NULL, the function returns the length of the needed + Finally, if @a dst is @NULL, the function returns the length of the needed buffer. */ - virtual size_t ToWChar(wchar_t * dst, size_t dstLen, - const char * src, + virtual size_t ToWChar(wchar_t* dst, size_t dstLen, + const char* src, size_t srcLen = wxNO_LEN); /** This function is deprecated, please use FromWChar() instead - Converts from Unicode to multibyte encoding. The semantics of this function (including the return value meaning) is the same as for wxMBConv::MB2WC. - Notice that when the function is called with a non-@NULL buffer, the - @e n parameter should be the size of the buffer and so it should take + @a n parameter should be the size of the buffer and so it should take into account the trailing @c NUL, which might take two or four bytes for some encodings (UTF-16 and UTF-32) and not one. */ -#define virtual size_t WC2MB(char* buf, const wchar_t* psz, size_t n) /* implementation is private */ + virtual size_t WC2MB(char* buf, const wchar_t* psz, size_t n); //@{ /** Converts from multibyte encoding to Unicode by calling wxMBConv::MB2WC, allocating a temporary wxWCharBuffer to hold the result. - The first overload takes a @c NUL-terminated input string. The second one takes a string of exactly the specified length and the string may include or not the @@ -394,12 +382,11 @@ public: appropriate number of @c NUL bytes (which is usually 1 but may be 2 or 4 for UTF-16 or UTF-32, see wxMBConv::GetMBNulLen), especially for long strings. - - If @e outLen is not-@NULL, it receives the length of the converted + If @a outLen is not-@NULL, it receives the length of the converted string. */ - const wxWCharBuffer cMB2WC(const char * in); - const wxWCharBuffer cMB2WC(const char * in, size_t inLen, + const wxWCharBuffer cMB2WC(const char* in); + const wxWCharBuffer cMB2WC(const char* in, size_t inLen, size_t outLen); //@} @@ -419,15 +406,13 @@ public: /** Converts from Unicode to multibyte encoding by calling WC2MB, allocating a temporary wxCharBuffer to hold the result. - The second overload of this function allows to convert a string of the given length @e inLen, whether it is @c NUL-terminated or not (for wide character strings, unlike for the multibyte ones, a single @c NUL is always enough). But notice that just as with @ref wxMBConv::mb2wc cMB2WC, it is more efficient to pass an already terminated string to this function as otherwise a copy is made internally. - - If @e outLen is not-@NULL, it receives the length of the converted + If @a outLen is not-@NULL, it receives the length of the converted string. */ const wxCharBuffer cWC2MB(const wchar_t* in); diff --git a/interface/stream.h b/interface/stream.h index 0ee93d52b1..d6fdad29d9 100644 --- a/interface/stream.h +++ b/interface/stream.h @@ -96,7 +96,7 @@ public: stream. It is advised to use this feature only in very local area of the program. - @sa @ref setbufferio() wxStreamBuffer:SetBufferIO + @see @ref setbufferio() wxStreamBuffer:SetBufferIO */ wxStreamBuffer(wxStreamBase& stream, BufMode mode); wxStreamBuffer(BufMode mode); @@ -120,7 +120,7 @@ public: (when it has the @true value) the stream buffer to resize dynamically the IO buffer. - @sa SetBufferIO() + @see SetBufferIO() */ void Fixed(bool fixed); @@ -130,7 +130,7 @@ public: bool FlushBuffer(); /** - Toggles the flushable flag. If @e flushable is disabled, no data are sent + Toggles the flushable flag. If @a flushable is disabled, no data are sent to the parent stream. */ void Flushable(bool flushable); @@ -138,12 +138,12 @@ public: /** Returns a pointer on the end of the stream buffer. */ - void * GetBufferEnd(); + void* GetBufferEnd(); /** Returns a pointer on the current position of the stream buffer. */ - void * GetBufferPos(); + void* GetBufferPos(); /** Returns the size of the buffer. @@ -153,12 +153,12 @@ public: /** Returns a pointer on the start of the stream buffer. */ - void * GetBufferStart(); + void* GetBufferStart(); /** Gets a single char from the stream buffer. It acts like the Read call. - @sa Read() + @see Read() */ char GetChar(); @@ -180,20 +180,20 @@ public: /** Puts a single char to the stream buffer. - @sa Read() + @see Read() */ void PutChar(char c); //@{ /** - Copies data to @e buffer. The function returns when @e buffer is full or when + Copies data to @e buffer. The function returns when @a buffer is full or when there isn't any more data in the current buffer. - @sa Write() + @see Write() */ - size_t Read(void * buffer, size_t size); - Return value size_t Read(wxStreamBuffer * buffer); + size_t Read(void* buffer, size_t size); + Return value size_t Read(wxStreamBuffer* buffer); //@} /** @@ -203,29 +203,23 @@ public: /** Changes the current position. - - @e mode may be one of the following: - + @a mode may be one of the following: @b wxFromStart - The position is counted from the start of the stream. @b wxFromCurrent - The position is counted from the current position of the stream. @b wxFromEnd - The position is counted from the end of the stream. - @returns Upon successful completion, it returns the new offset as - measured in bytes from the beginning of the stream. - Otherwise, it returns wxInvalidOffset. + measured in bytes from the beginning of the stream. + Otherwise, it returns wxInvalidOffset. */ off_t Seek(off_t pos, wxSeekMode mode); @@ -234,7 +228,7 @@ public: Destroys or invalidates the previous IO buffer and allocates a new one of the specified size. - @sa Fixed(), Flushable() + @see Fixed(), Flushable() */ void SetBufferIO(char* buffer_start, char* buffer_end); Remarks See also @@ -263,13 +257,12 @@ public: the stream. @returns Returns the current position in the stream if possible, - wxInvalidOffset in the other case. + wxInvalidOffset in the other case. */ off_t Tell(); /** Truncates the buffer to the current position. - Note: Truncate() cannot be used to enlarge the buffer. This is usually not needed since the buffer expands automatically. */ @@ -279,8 +272,8 @@ public: /** See Read(). */ - size_t Write(const void * buffer, size_t size); - size_t Write(wxStreamBuffer * buffer); + size_t Write(const void* buffer, size_t size); + size_t Write(wxStreamBuffer* buffer); //@} }; @@ -311,7 +304,6 @@ public: Closes the stream, returning @false if an error occurs. The stream is closed implicitly in the destructor if Close() is not called explicitly. - If this stream wraps another stream or some other resource such as a file, then the underlying resource is closed too if it is owned by this stream, or left open otherwise. @@ -329,16 +321,15 @@ public: Puts the specified character in the output queue and increments the stream position. */ -#define void PutC(char c) /* implementation is private */ + void PutC(char c); /** Changes the stream current position. @param pos - Offset to seek to. - + Offset to seek to. @param mode - One of wxFromStart, wxFromEnd, wxFromCurrent. + One of wxFromStart, wxFromEnd, wxFromCurrent. @returns The new stream position or wxInvalidOffset on error. */ @@ -355,7 +346,7 @@ public: in the current stream. The data is read until an error is raised by one of the two streams. */ - wxOutputStream Write(const void * buffer, size_t size); + wxOutputStream Write(const void* buffer, size_t size); wxOutputStream Write(wxInputStream& stream_in); //@} }; @@ -395,7 +386,6 @@ public: /** Returns @true if this factory can handle the given protocol, MIME type, HTTP encoding or file extension. - When using wxSTREAM_FILEEXT for the second parameter, the first parameter can be a complete filename rather than just an extension. */ @@ -407,7 +397,6 @@ public: type, HTTP encoding or file extension. Returns a pointer to the class factory if found, or @NULL otherwise. It does not give away ownership of the factory. - When using wxSTREAM_FILEEXT for the second parameter, the first parameter can be a complete filename rather than just an extension. */ @@ -417,8 +406,8 @@ public: //@{ /** GetFirst and GetNext can be used to enumerate the available factories. - For example, to list them: + GetFirst()/GetNext() return a pointer to a factory or @NULL if no more are available. They do not give away ownership of the factory. */ @@ -436,15 +425,13 @@ public: Returns the protocols, MIME types, HTTP encodings or file extensions supported by this factory, as an array of null terminated strings. It does not give away ownership of the array or strings. - For example, to list the file extensions a factory supports: */ - const wxChar * const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL); + const wxChar* const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL); //@{ /** Create a new input or output stream to decompress or compress a given stream. - If the parent stream is passed as a pointer then the new filter stream takes ownership of it. If it is passed by reference then it does not. */ @@ -455,7 +442,7 @@ public: //@} /** - Remove the file extension of @e location if it is one of the file + Remove the file extension of @a location if it is one of the file extensions handled by this factory. */ wxString PopExtension(const wxString& location); @@ -463,15 +450,12 @@ public: /** Adds this class factory to the list returned by @ref getfirst() GetFirst()/GetNext. - It is not necessary to do this to use the filter streams. It is usually used when implementing streams, typically the implementation will add a static instance of its factory class. - It can also be used to change the order of a factory already in the list, bringing it to the front. This isn't a thread safe operation so can't be done when other threads are running that will be using the list. - The list does not take ownership of the factory. */ void PushFront(); @@ -479,10 +463,8 @@ public: /** Removes this class factory from the list returned by @ref getfirst() GetFirst()/GetNext. - Removing from the list isn't a thread safe operation so can't be done when other threads are running that will be using the list. - The list does not own the factories, so removing a factory does not delete it. */ void Remove(); @@ -510,7 +492,6 @@ public: //@{ /** Initializes a "filter" stream. - If the parent stream is passed as a pointer then the new filter stream takes ownership of it. If it is passed by reference then it does not. */ @@ -542,7 +523,6 @@ public: //@{ /** Initializes a "filter" stream. - If the parent stream is passed as a pointer then the new filter stream takes ownership of it. If it is passed by reference then it does not. */ @@ -629,13 +609,13 @@ public: Returns @true after an attempt has been made to read past the end of the stream. */ -#define bool Eof() /* implementation is private */ + bool Eof(); /** Returns the first character in the input queue and removes it, blocking until it appears if necessary. */ -#define char GetC() /* implementation is private */ + char GetC(); /** Returns the last number of bytes read. @@ -653,9 +633,9 @@ public: The data is read until an error is raised by one of the two streams. @returns This function returns a reference on the current object, so the - user can test any states of the stream right away. + user can test any states of the stream right away. */ - wxInputStream Read(void * buffer, size_t size); + wxInputStream Read(void* buffer, size_t size); Warning Return value This function returns a reference on the current object, so the user can test any states of the stream right away. @@ -666,10 +646,9 @@ public: Changes the stream current position. @param pos - Offset to seek to. - + Offset to seek to. @param mode - One of wxFromStart, wxFromEnd, wxFromCurrent. + One of wxFromStart, wxFromEnd, wxFromCurrent. @returns The new stream position or wxInvalidOffset on error. */ @@ -721,25 +700,20 @@ public: /** This function returns the last error. - @b wxSTREAM_NO_ERROR - No error occurred. @b wxSTREAM_EOF - An End-Of-File occurred. @b wxSTREAM_WRITE_ERROR - A generic error occurred on the last write call. @b wxSTREAM_READ_ERROR - A generic error occurred on the last read call. */ wxStreamError GetLastError(); @@ -748,14 +722,12 @@ public: Returns the length of the stream in bytes. If the length cannot be determined (this is always the case for socket streams for example), returns @c wxInvalidOffset. - This function is new since wxWidgets version 2.5.4 */ wxFileOffset GetLength(); /** GetLength() - This function returns the size of the stream. For example, for a file it is the size of the file. */ @@ -764,9 +736,9 @@ public: /** Returns @true if no error occurred on the stream. - @sa GetLastError() + @see GetLastError() */ -#define virtual bool IsOk() /* implementation is private */ + virtual bool IsOk(); /** Returns @true if the streams supports seeking to arbitrary offsets. @@ -794,5 +766,5 @@ public: /** See OnSysRead(). */ - size_t OnSysWrite(const void * buffer, size_t bufsize); + size_t OnSysWrite(const void* buffer, size_t bufsize); }; diff --git a/interface/string.h b/interface/string.h index 4a2d2edb4d..11639efeca 100644 --- a/interface/string.h +++ b/interface/string.h @@ -47,7 +47,7 @@ class wxStringBuffer public: /** Constructs a writable string buffer object associated with the given string - and containing enough space for at least @e len characters. Basically, this + and containing enough space for at least @a len characters. Basically, this is equivalent to calling wxString::GetWriteBuf and saving the result. */ @@ -63,7 +63,7 @@ public: Returns the writable pointer to a buffer of the size at least equal to the length specified in the constructor. */ - wxChar * operator wxChar *(); + wxChar* operator wxChar *(); }; @@ -106,15 +106,15 @@ class wxString public: //@{ /** - Initializes the string from first @e nLength characters of C string. + Initializes the string from first @a nLength characters of C string. The default value of @c wxSTRING_MAXLEN means take all the string. In Unicode build, @e conv's wxMBConv::MB2WC method is called to - convert @e psz to wide string (the default converter uses current locale's + convert @a psz to wide string (the default converter uses current locale's charset). It is ignored in ANSI build. - @sa @ref overview_mbconvclasses "wxMBConv classes", @ref mbstr() - mb_str, @ref wcstr() wc_str + @see @ref overview_mbconvclasses "wxMBConv classes", @ref mbstr() + mb_str, @ref wcstr() wc_str */ wxString(); wxString(const wxString& x); @@ -136,23 +136,24 @@ public: /** Gets all the characters after the first occurrence of @e ch. - Returns the empty string if @e ch is not found. + Returns the empty string if @a ch is not found. */ wxString AfterFirst(wxChar ch); /** Gets all the characters after the last occurrence of @e ch. - Returns the whole string if @e ch is not found. + Returns the whole string if @a ch is not found. */ wxString AfterLast(wxChar ch); /** - Preallocate enough space for wxString to store @e nLen characters. This function + Preallocate enough space for wxString to store @a nLen characters. This function may be used to increase speed when the string is constructed by repeated concatenation as in + because it will avoid the need to reallocate string memory many times (in case of long strings). Note that it does not set the maximal length of a string - it - will still expand if more than @e nLen characters are stored in it. Also, it + will still expand if more than @a nLen characters are stored in it. Also, it does not truncate the existing string (use Truncate() for this) even if its current length is greater than @e nLen @@ -161,7 +162,7 @@ public: //@{ /** - Concatenates character @e ch to this string, @e count times, returning a + Concatenates character @a ch to this string, @a count times, returning a reference to it. */ @@ -171,13 +172,13 @@ public: /** Gets all characters before the first occurrence of @e ch. - Returns the whole string if @e ch is not found. + Returns the whole string if @a ch is not found. */ wxString BeforeFirst(wxChar ch); /** Gets all characters before the last occurrence of @e ch. - Returns the empty string if @e ch is not found. + Returns the empty string if @a ch is not found. */ wxString BeforeLast(wxChar ch); @@ -185,7 +186,6 @@ public: The MakeXXX() variants modify the string in place, while the other functions return a new string which contains the original text converted to the upper or lower case and leave the original string unchanged. - MakeUpper() Upper() @@ -204,13 +204,11 @@ public: failure in @ref overview_debuggingoverview "debug build", but no checks are done in release builds. - This section also contains both implicit and explicit conversions to C style strings. Although implicit conversion is quite convenient, it is advised to use explicit @ref cstr() c_str method for the sake of clarity. Also see overview for the cases where it is necessary to use it. - GetChar() GetWritableChar() @@ -235,7 +233,6 @@ public: /** Empties the string and frees memory occupied by it. - See also: Empty() */ void Clear(); @@ -243,12 +240,10 @@ public: //@{ /** Case-sensitive comparison. - Returns a positive value if the string is greater than the argument, zero if it is equal to it or a negative value if it is less than the argument (same semantics as the standard @e strcmp() function). - See also CmpNoCase(), IsSameAs(). */ int Cmp(const wxString& s); @@ -258,12 +253,10 @@ public: //@{ /** Case-insensitive comparison. - Returns a positive value if the string is greater than the argument, zero if it is equal to it or a negative value if it is less than the argument (same semantics as the standard @e strcmp() function). - See also Cmp(), IsSameAs(). */ int CmpNoCase(const wxString& s); @@ -272,7 +265,6 @@ public: /** Case-sensitive comparison. Returns 0 if equal, 1 if greater or -1 if less. - This is a wxWidgets 1.xx compatibility function; use Cmp() instead. */ int CompareTo(const wxChar* psz, caseCompare cmp = exact); @@ -286,16 +278,13 @@ public: @true value if the strings are the same and not 0 (which is usually @false in C) as @c Cmp() does. - Matches() is a poor man's regular expression matcher: it only understands '*' and '?' metacharacters in the sense of DOS command line interpreter. - StartsWith() is helpful when parsing a line of text which should start with some predefined prefix and is more efficient than doing direct string comparison as you would also have to precalculate the length of the prefix then. - Cmp() CmpNoCase() @@ -332,7 +321,6 @@ public: Anything may be concatenated (appended to) with a string. However, you can't append something to a C string (including literal constants), so to do this it should be converted to a wxString first. - @ref operatorout() "operator " @ref plusequal() "operator +=" @@ -350,7 +338,6 @@ public: a single character or a wide (UNICODE) string. For all constructors (except the default which creates an empty string) there is also a corresponding assignment operator. - @ref construct() wxString @ref operatorassign() "operator =" @@ -361,7 +348,6 @@ public: /** Returns @true if target appears anywhere in wxString; else @false. - This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ @@ -372,7 +358,6 @@ public: floating point numbers. All three functions take a pointer to the variable to put the numeric value in and return @true if the @b entire string could be converted to a number. - ToLong() ToLongLong() @@ -387,7 +372,6 @@ public: /** Makes the string empty, but doesn't free memory occupied by the string. - See also: Clear(). */ void Empty(); @@ -395,25 +379,24 @@ public: /** This function can be used to test if the string ends with the specified @e suffix. If it does, the function will return @true and put the - beginning of the string before the suffix into @e rest string if it is not + beginning of the string before the suffix into @a rest string if it is not @NULL. Otherwise, the function returns @false and doesn't modify the @e rest. */ - bool EndsWith(const wxString& suffix, wxString rest = @NULL); + bool EndsWith(const wxString& suffix, wxString rest = NULL); //@{ /** Searches for the given string. Returns the starting index, or @c wxNOT_FOUND if not found. */ - int Find(wxUniChar ch, bool fromEnd = @false); + int Find(wxUniChar ch, bool fromEnd = false); int Find(const wxString& sub); //@} //@{ /** Same as Find(). - This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ @@ -426,21 +409,20 @@ public: This static function returns the string containing the result of calling Printf() with the passed parameters on it. - @sa FormatV(), Printf() + @see FormatV(), Printf() */ - static wxString Format(const wxChar format, ...); + static wxString Format(const wxChar format, ...); /** This static function returns the string containing the result of calling PrintfV() with the passed parameters on it. - @sa Format(), PrintfV() + @see Format(), PrintfV() */ static wxString FormatV(const wxChar format, va_list argptr); /** - Returns the number of occurrences of @e ch in the string. - + Returns the number of occurrences of @a ch in the string. This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ @@ -450,13 +432,11 @@ public: /** Converts given buffer of binary data from 8-bit string to wxString. In Unicode build, the string is interpreted as being in ISO-8859-1 encoding. The version - without @e len parameter takes NUL-terminated data. - + without @a len parameter takes NUL-terminated data. This is a convenience method useful when storing binary data in wxString. - This function is new since wxWidgets version 2.8.4 - @sa wxString::To8BitData + @see wxString::To8BitData */ static wxString From8BitData(const char* buf, size_t len); static wxString From8BitData(const char* buf); @@ -480,8 +460,7 @@ public: //@{ /** Converts C string encoded in UTF-8 to wxString. - - Note that this method assumes that @e s is a valid UTF-8 sequence and + Note that this method assumes that @a s is a valid UTF-8 sequence and doesn't do any validation in release builds, it's validity is only checked in debug builds. */ @@ -490,7 +469,7 @@ public: //@} /** - Returns the character at position @e n (read-only). + Returns the character at position @a n (read-only). */ wxChar GetChar(size_t n); @@ -506,13 +485,11 @@ public: wxChar GetWritableChar(size_t n); /** - Returns a writable buffer of at least @e len bytes. + Returns a writable buffer of at least @a len bytes. It returns a pointer to a new memory block, and the existing data will not be copied. - Call UngetWriteBuf() as soon as possible to put the string back into a reasonable state. - This method is deprecated, please use wxStringBuffer or wxStringBufferLength instead. @@ -522,7 +499,6 @@ public: //@{ /** Same as Find(). - This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ @@ -532,7 +508,6 @@ public: /** Returns @true if the string contains only ASCII characters. - This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ @@ -545,7 +520,6 @@ public: /** Returns @true if the string is empty (same as wxString::IsEmpty). - This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ @@ -553,7 +527,6 @@ public: /** Returns @true if the string is an integer (with possible sign). - This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ @@ -562,20 +535,17 @@ public: //@{ /** Test whether the string is equal to the single character @e c. The test is - case-sensitive if @e caseSensitive is @true (default) or not if it is @c + case-sensitive if @a caseSensitive is @true (default) or not if it is @c @false. - Returns @true if the string is equal to the character, @false otherwise. - See also Cmp(), CmpNoCase() */ - bool IsSameAs(const wxChar* psz, bool caseSensitive = @true); - bool IsSameAs(wxChar c, bool caseSensitive = @true); + bool IsSameAs(const wxChar* psz, bool caseSensitive = true); + bool IsSameAs(wxChar c, bool caseSensitive = true); //@} /** Returns @true if the string is a word. - This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ @@ -584,7 +554,6 @@ public: //@{ /** Returns a reference to the last character (writable). - This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ @@ -593,18 +562,17 @@ public: //@} /** - Returns the first @e count characters of the string. + Returns the first @a count characters of the string. */ wxString Left(size_t count); /** Returns the length of the string. */ -#define size_t Len() /* implementation is private */ + size_t Len(); /** Returns the length of the string (same as Len). - This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ @@ -617,7 +585,6 @@ public: /** Same as MakeLower. - This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ @@ -646,7 +613,6 @@ public: and wxStringBufferLength classes may be very useful when working with some external API which requires the caller to provide a writable buffer. - Alloc() Shrink() @@ -659,13 +625,12 @@ public: /** Returns a substring starting at @e first, with length @e count, or the rest of - the string if @e count is the default value. + the string if @a count is the default value. */ -#define wxString Mid(size_t first, size_t count = wxSTRING_MAXLEN) /* implementation is private */ + wxString Mid(size_t first, size_t count = wxSTRING_MAXLEN); /** Other string functions. - Trim() Truncate() @@ -675,31 +640,30 @@ public: /** - Adds @e count copies of @e pad to the beginning, or to the end of the string + Adds @a count copies of @a pad to the beginning, or to the end of the string (the default). - Removes spaces from the left or from the right (default). */ -#define wxString Pad(size_t count, wxChar pad = ' ', - bool fromRight = @true) /* implementation is private */ + wxString Pad(size_t count, wxChar pad = ' ', + bool fromRight = true); /** - Prepends @e str to this string, returning a reference to this string. + Prepends @a str to this string, returning a reference to this string. */ wxString Prepend(const wxString& str); /** Similar to the standard function @e sprintf(). Returns the number of characters written, or an integer less than zero on error. - 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 @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. */ - int Printf(const wxChar* pszFormat, ...); + int Printf(const wxChar* pszFormat, ...); /** Similar to vprintf. Returns the number of characters written, or an integer @@ -710,8 +674,7 @@ public: //@{ /** - Removes @e len characters from the string, starting at @e pos. - + Removes @a len characters from the string, starting at @e pos. This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ @@ -726,23 +689,20 @@ public: /** Replace first (or all) occurrences of substring with another one. - @e replaceAll: global replace (default), or only the first occurrence. - Returns the number of replacements made. */ size_t Replace(const wxString& strOld, const wxString& strNew, - bool replaceAll = @true); + bool replaceAll = true); /** - Returns the last @e count characters. + Returns the last @a count characters. */ wxString Right(size_t count); /** These functions replace the standard @e strchr() and @e strstr() functions. - Find() Replace() @@ -763,16 +723,15 @@ public: /** This function can be used to test if the string starts with the specified @e prefix. If it does, the function will return @true and put the rest - of the string (i.e. after the prefix) into @e rest string if it is not + of the string (i.e. after the prefix) into @a rest string if it is not @NULL. Otherwise, the function returns @false and doesn't modify the @e rest. */ - bool StartsWith(const wxString& prefix, wxString rest = @NULL); + bool StartsWith(const wxString& prefix, wxString rest = NULL); /** These functions return the string length and check whether the string is empty or empty it. - Len() IsEmpty() @@ -788,16 +747,14 @@ public: /** Strip characters at the front and/or end. The same as Trim except that it doesn't change this string. - This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ wxString Strip(stripType s = trailing); /** - Returns the part of the string between the indices @e from and @e to + Returns the part of the string between the indices @a from and @e to inclusive. - This is a wxWidgets 1.xx compatibility function, use Mid() instead (but note that parameters have different meaning). */ @@ -807,7 +764,6 @@ public: These functions allow to extract substring from this string. All of them don't modify the original string and return a new string containing the extracted substring. - Mid() @ref operatorparenth() operator @@ -834,12 +790,10 @@ public: /** Converts the string to an 8-bit string in ISO-8859-1 encoding in the form of a wxCharBuffer (Unicode builds only). - This is a convenience method useful when storing binary data in wxString. - This function is new since wxWidgets version 2.8.4 - @sa wxString::From8BitData + @see wxString::From8BitData */ const char* To8BitData(); const wxCharBuffer To8BitData(); @@ -849,7 +803,6 @@ public: /** Converts the string to an ASCII, 7-bit string in the form of a wxCharBuffer (Unicode builds only) or a C string (ANSI builds). - Note that this conversion only works if the string contains only ASCII characters. The @ref mbstr() mb_str method provides more powerful means of converting wxString to C string. @@ -861,21 +814,20 @@ public: /** Attempts to convert the string to a floating point number. Returns @true on success (the number is stored in the location pointed to by @e val) or @false - if the string does not represent such number (the value of @e val is not + if the string does not represent such number (the value of @a val is not modified in this case). - @sa ToLong(), ToULong() + @see ToLong(), ToULong() */ bool ToDouble(double val); /** Attempts to convert the string to a signed integer in base @e base. Returns @true on success in which case the number is stored in the location - pointed to by @e val or @false if the string does not represent a - valid number in the given base (the value of @e val is not modified + pointed to by @a val or @false if the string does not represent a + valid number in the given base (the value of @a val is not modified in this case). - - The value of @e base must be comprised between 2 and 36, inclusive, or + The value of @a base must be comprised between 2 and 36, inclusive, or be a special value 0 which means that the usual rules of @c C numbers are applied: if the number starts with @c 0x it is considered to be in base 16, if it starts with @c 0 - in base 8 and in base 10 otherwise. Note @@ -883,43 +835,40 @@ public: which may have leading zeroes as they can yield unexpected (to the user not familiar with C) results. - @sa ToDouble(), ToULong() + @see ToDouble(), ToULong() */ bool ToLong(long val, int base = 10); /** This is exactly the same as ToLong() but works with 64 bit integer numbers. - Notice that currently it doesn't work (always returns @false) if parsing of 64 bit numbers is not supported by the underlying C run-time library. Compilers with C99 support and Microsoft Visual C++ version 7 and higher do support this. - @sa ToLong(), ToULongLong() + @see ToLong(), ToULongLong() */ bool ToLongLong(wxLongLong_t val, int base = 10); /** Attempts to convert the string to an unsigned integer in base @e base. Returns @true on success in which case the number is stored in the - location pointed to by @e val or @false if the string does not - represent a valid number in the given base (the value of @e val is not + location pointed to by @a val or @false if the string does not + represent a valid number in the given base (the value of @a val is not modified in this case). Please notice that this function behaves in the same way as the standard @c strtoul() and so it simply converts negative numbers to unsigned representation instead of rejecting them (e.g. -1 is returned as @c ULONG_MAX). - See ToLong() for the more detailed - description of the @e base parameter. + description of the @a base parameter. - @sa ToDouble(), ToLong() + @see ToDouble(), ToLong() */ bool ToULong(unsigned long val, int base = 10); /** This is exactly the same as ToULong() but works with 64 bit integer numbers. - Please see ToLongLong() for additional remarks. */ bool ToULongLong(wxULongLong_t val, int base = 10); @@ -936,7 +885,7 @@ public: Removes white-space (space, tabs, form feed, newline and carriage return) from the left or from the right end of the string (right is default). */ - wxString Trim(bool fromRight = @true); + wxString Trim(bool fromRight = true); /** Truncate the string to the given length. @@ -948,14 +897,12 @@ public: Puts the string back into a reasonable state (in which it can be used normally), after GetWriteBuf() was called. - - The version of the function without the @e len parameter will calculate the + The version of the function without the @a len parameter will calculate the new string length itself assuming that the string is terminated by the first @c NUL character in it while the second one will use the specified length and thus is the only version which should be used with the strings with embedded @c NULs (it is also slightly more efficient as @c strlen() doesn't have to be called). - This method is deprecated, please use wxStringBuffer or wxStringBufferLength instead. @@ -971,7 +918,6 @@ public: /** The same as MakeUpper. - This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ @@ -982,6 +928,7 @@ public: insertion operators exist (for basic types only). Additionally, the Format() function allows to use simply append formatted value to a string: + Format() FormatV() @@ -997,17 +944,16 @@ public: /** Returns a pointer to the string data (@c const char* in ANSI build, @c const wchar_t* in Unicode build). - Note that the returned value is not convertible to @c char* or @c wchar_t*, use @ref charstr() char_str or @ref wcharstr() wchar_string if you need to pass string value to a function expecting non-const pointer. - @sa @ref mbstr() mb_str, @ref wcstr() wc_str, @ref - fnstr() fn_str, @ref charstr() char_str, @ref - wcharstr() wchar_string + @see @ref mbstr() mb_str, @ref wcstr() wc_str, @ref + fnstr() fn_str, @ref charstr() char_str, @ref + wcharstr() wchar_string */ - const wxChar * c_str(); + const wxChar* c_str(); /** Returns an object with string data that is implicitly convertible to @@ -1016,9 +962,9 @@ public: don't have const-correct API. Use wxStringBuffer if you want to modify the string. - @sa @ref mbstr() mb_str, @ref wcstr() wc_str, @ref - fnstr() fn_str, @ref cstr() c_str, @ref - wcharstr() wchar_str + @see @ref mbstr() mb_str, @ref wcstr() wc_str, @ref + fnstr() fn_str, @ref cstr() c_str, @ref + wcharstr() wchar_str */ wxWritableCharBuffer char_str(const wxMBConv& conv = wxConvLibc); @@ -1030,7 +976,7 @@ public: or C string in charset matching the @c wxConvFileName object, depending on the OS. - @sa wxMBConv, @ref wcstr() wc_str, @ref wcstr() mb_str + @see wxMBConv, @ref wcstr() wc_str, @ref wcstr() mb_str */ const wchar_t* fn_str(); const char* fn_str(); @@ -1045,8 +991,8 @@ public: as @ref cstr() c_str. The macro wxWX2MBbuf is defined as the correct return type (without const). - @sa wxMBConv, @ref cstr() c_str, @ref wcstr() wc_str, @ref - fnstr() fn_str, @ref charstr() char_str + @see wxMBConv, @ref cstr() c_str, @ref wcstr() wc_str, @ref + fnstr() fn_str, @ref charstr() char_str */ const char* mb_str(const wxMBConv& conv = wxConvLibc); const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc); @@ -1128,7 +1074,6 @@ public: This allows the tests for @NULLness of a @e const wxChar * pointer and emptiness of the string to look the same in the code and makes it easier to port old code to wxString. - See also IsEmpty(). */ bool operator!(); @@ -1157,8 +1102,8 @@ public: as @ref cstr() c_str. The macro wxWX2WCbuf is defined as the correct return type (without const). - @sa wxMBConv, @ref cstr() c_str, @ref wcstr() mb_str, @ref - fnstr() fn_str, @ref wcharstr() wchar_str + @see wxMBConv, @ref cstr() c_str, @ref wcstr() mb_str, @ref + fnstr() fn_str, @ref wcharstr() wchar_str */ const wchar_t* wc_str(const wxMBConv& conv); const wxWCharBuffer wc_str(const wxMBConv& conv); @@ -1171,16 +1116,15 @@ public: passing strings to legacy libraries that don't have const-correct API. Use wxStringBuffer if you want to modify the string. - @sa @ref mbstr() mb_str, @ref wcstr() wc_str, @ref - fnstr() fn_str, @ref cstr() c_str, @ref - charstr() char_str + @see @ref mbstr() mb_str, @ref wcstr() wc_str, @ref + fnstr() fn_str, @ref cstr() c_str, @ref + charstr() char_str */ wxWritableWCharBuffer wchar_str(); /** These functions are deprecated, please consider using new wxWidgets 2.0 functions instead of them (or, even better, std::string compatible variants). - CompareTo() Contains() @@ -1263,7 +1207,7 @@ class wxStringBufferLength public: /** Constructs a writable string buffer object associated with the given string - and containing enough space for at least @e len characters. Basically, this + and containing enough space for at least @a len characters. Basically, this is equivalent to calling wxString::GetWriteBuf and saving the result. */ @@ -1277,8 +1221,7 @@ public: /** Sets the internal length of the string referred to by wxStringBufferLength to - @e nLength characters. - + @a nLength characters. Must be called before wxStringBufferLength destructs. */ void SetLength(size_t nLength); @@ -1287,7 +1230,7 @@ public: Returns the writable pointer to a buffer of the size at least equal to the length specified in the constructor. */ - wxChar * operator wxChar *(); + wxChar* operator wxChar *(); }; diff --git a/interface/sysopt.h b/interface/sysopt.h index 879e600c55..63c9d68d0f 100644 --- a/interface/sysopt.h +++ b/interface/sysopt.h @@ -35,21 +35,19 @@ public: /** Gets an option. The function is case-insensitive to @e name. - Returns empty string if the option hasn't been set. - @sa SetOption(), GetOptionInt(), - HasOption() + @see SetOption(), GetOptionInt(), + HasOption() */ wxString GetOption(const wxString& name); /** Gets an option as an integer. The function is case-insensitive to @e name. - If the option hasn't been set, this function returns 0. - @sa SetOption(), GetOption(), - HasOption() + @see SetOption(), GetOption(), + HasOption() */ int GetOptionInt(const wxString& name); @@ -57,13 +55,13 @@ public: Returns @true if the given option is present. The function is case-insensitive to @e name. - @sa SetOption(), GetOption(), - GetOptionInt() + @see SetOption(), GetOption(), + GetOptionInt() */ bool HasOption(const wxString& name); /** - Returns @true if the option with the given @e name had been set to 0 + Returns @true if the option with the given @a name had been set to 0 value. This is mostly useful for boolean options for which you can't use @c GetOptionInt(name) == 0 as this would also be @true if the option hadn't been set at all. diff --git a/interface/tarstrm.h b/interface/tarstrm.h index e5fcbcd912..8ee3d5d9f3 100644 --- a/interface/tarstrm.h +++ b/interface/tarstrm.h @@ -34,11 +34,10 @@ class wxTarInputStream : public wxArchiveInputStream public: //@{ /** - Constructor. In a Unicode build the second parameter @e conv is + Constructor. In a Unicode build the second parameter @a conv is used to translate fields from the standard tar header into Unicode. It has - no effect on the stream's data. @e conv is only used for the standard + no effect on the stream's data. @a conv is only used for the standard tar headers, any pax extended headers are always UTF-8 encoded. - If the parent stream is passed as a pointer then the new filter stream takes ownership of it. If it is passed by reference then it does not. */ @@ -63,9 +62,8 @@ public: /** Closes the current entry if one is open, then opens the entry specified - by the @e entry object. - - @e entry should be from the same tar file, and the tar should + by the @a entry object. + @a entry should be from the same tar file, and the tar should be on a seekable stream. */ bool OpenEntry(wxTarEntry& entry); @@ -117,20 +115,16 @@ public: /** If the parent stream is passed as a pointer then the new filter stream takes ownership of it. If it is passed by reference then it does not. - - In a Unicode build the third parameter @e conv is used to translate the + In a Unicode build the third parameter @a conv is used to translate the headers fields into an 8-bit encoding. It has no effect on the stream's data. - - When the @e format is @e wxTAR_PAX, pax extended headers are generated + When the @a format is @e wxTAR_PAX, pax extended headers are generated when any header field will not fit the standard tar header block or if it uses any non-ascii characters. - Extended headers are stored as extra 'files' within the tar, and will be extracted as such by any other tar program that does not understand them. - The @e conv parameter only affect the standard tar headers, the extended + The @a conv parameter only affect the standard tar headers, the extended headers are always UTF-8 encoded. - - When the @e format is @e wxTAR_USTAR, no extended headers are + When the @a format is @e wxTAR_USTAR, no extended headers are generated, and instead a warning message is logged if any header field overflows. */ @@ -169,17 +163,15 @@ public: bool CopyArchiveMetaData(wxTarInputStream& s); /** - Takes ownership of @e entry and uses it to create a new entry - in the tar. @e entry is then opened in @e inputStream and its contents + Takes ownership of @a entry and uses it to create a new entry + in the tar. @a entry is then opened in @a inputStream and its contents copied to this stream. - For some other archive formats CopyEntry() is much more efficient than transferring the data using Read() and Write() since it will copy them without decompressing and recompressing them. For tar however it makes no difference. - - For tars on seekable streams, @e entry must be from the same tar file - as @e stream. For non-seekable streams, @e entry must also be the + For tars on seekable streams, @a entry must be from the same tar file + as @e stream. For non-seekable streams, @a entry must also be the last thing read from @e inputStream. */ bool CopyEntry(wxTarEntry* entry, wxTarInputStream& inputStream); @@ -187,7 +179,6 @@ public: //@{ /** The tar is zero padded to round its size up to @e BlockingFactor * 512 bytes. - Defaults to 10 for @e wxTAR_PAX and 20 for @e wxTAR_USTAR (see the @ref wxtaroutputstream() constructor), as specified in the POSIX standards. @@ -198,11 +189,9 @@ public: /** ) - Create a new directory entry (see wxArchiveEntry::IsDir) with the given name and timestamp. - PutNextEntry() can also be used to create directory entries, by supplying a name with a trailing path separator. @@ -212,7 +201,6 @@ public: //@{ /** , @b wxFileOffset@e size = wxInvalidOffset) - Create a new entry with the given name, timestamp and size. */ bool PutNextEntry(wxTarEntry* entry); @@ -323,7 +311,6 @@ public: //@{ /** The size of the entry's data in bytes. - The tar archive format stores the entry's size ahead of the entry's data. Therefore when creating an archive on a non-seekable stream it is necessary to supply the correct size when each entry is created. For seekable streams this @@ -338,6 +325,7 @@ public: //@{ /** Returns the type of the entry. It should be one of the following: + When creating archives use just these values. When reading archives any other values should be treated as @e wxTAR_REGTYPE. */ @@ -355,7 +343,7 @@ public: wxString GetInternalName(); wxString GetInternalName(const wxString& name, wxPathFormat format = wxPATH_NATIVE, - bool* pIsDir = @NULL); + bool* pIsDir = NULL); //@} /** diff --git a/interface/taskbar.h b/interface/taskbar.h index 5d794a8ae4..f842f22983 100644 --- a/interface/taskbar.h +++ b/interface/taskbar.h @@ -33,7 +33,6 @@ public: This method is called by the library when the user requests popup menu (on Windows and Unix platforms, this is when the user right-clicks the icon). Override this function in order to provide popup menu associated with the icon. - If CreatePopupMenu returns @NULL (this happens by default), no menu is shown, otherwise the menu is displayed and then deleted by the library as soon as the user dismisses it. @@ -57,7 +56,7 @@ public: /** Returns @true if the object initialized successfully. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** Pops up a menu at the current mouse position. The events can be handled by diff --git a/interface/textctrl.h b/interface/textctrl.h index ddf5580af4..f489c8e037 100644 --- a/interface/textctrl.h +++ b/interface/textctrl.h @@ -41,11 +41,11 @@ public: //@} /** - Applies the attributes in @e style to the original object, but not those - attributes from @e style that are the same as those in @e compareWith (if passed). + Applies the attributes in @a style to the original object, but not those + attributes from @a style that are the same as those in @a compareWith (if passed). */ bool Apply(const wxTextAttr& style, - const wxTextAttr* compareWith = @NULL); + const wxTextAttr* compareWith = NULL); /** Creates a font from the font attributes. @@ -74,12 +74,10 @@ public: Returns the standard bullet name, applicable if the bullet style is wxTEXT_ATTR_BULLET_STYLE_STANDARD. Currently the following standard bullet names are supported: - @c standard/circle @c standard/square @c standard/diamond @c standard/triangle - For wxRichTextCtrl users only: if you wish your rich text controls to support further bullet graphics, you can derive a class from wxRichTextRenderer or wxRichTextStdRenderer, override @c @@ -239,7 +237,7 @@ public: generates a wxTextUrlEvent when the content is clicked. */ -#define const wxString GetURL() /* implementation is private */ + const wxString GetURL(); /** Returns @true if the attribute object specifies alignment. @@ -278,7 +276,7 @@ public: bool HasCharacterStyleName(); /** - Returns @true if the @e flag is present in the attribute object's flag + Returns @true if the @a flag is present in the attribute object's flag bitlist. */ bool HasFlag(long flag); @@ -384,7 +382,7 @@ public: /** Returns @true if the attribute object specifies a URL. */ -#define bool HasURL() /* implementation is private */ + bool HasURL(); /** Returns @true if the object represents a character style, that is, @@ -406,8 +404,8 @@ public: //@{ /** - Creates a new @c wxTextAttr which is a merge of @e base and - @e overlay. Properties defined in @e overlay take precedence over those + Creates a new @c wxTextAttr which is a merge of @a base and + @e overlay. Properties defined in @a overlay take precedence over those in @e base. Properties undefined/invalid in both are undefined in the result. */ @@ -419,7 +417,6 @@ public: /** Sets the paragraph alignment. These are the possible values for @e alignment: - Of these, wxTEXT_ALIGNMENT_JUSTIFIED is unimplemented. In future justification may be supported when printing or previewing, only. @@ -453,7 +450,6 @@ public: /** Sets the bullet style. The following styles can be passed: - Currently wxTEXT_ATTR_BULLET_STYLE_BITMAP is not supported. */ void SetBulletStyle(int style); @@ -513,7 +509,6 @@ public: /** Sets the left indent and left subindent in tenths of a millimetre. - The sub-indent is an offset from the left of the paragraph, and is used for all but the first line in a paragraph. A positive value will cause the first line to appear @@ -521,7 +516,6 @@ public: of the subsequent lines, and a negative value will cause the first line to be indented relative to the subsequent lines. - wxRichTextBuffer uses indentation to render a bulleted item. The left indent is the distance between the margin and the bullet. The content of the paragraph, including the first @@ -533,7 +527,7 @@ public: void SetLeftIndent(int indent, int subIndent = 0); /** - Sets the line spacing. @e spacing is a multiple, where 10 means single-spacing, + Sets the line spacing. @a spacing is a multiple, where 10 means single-spacing, 15 means 1.5 spacing, and 20 means double spacing. The following constants are defined for convenience: */ @@ -556,7 +550,7 @@ public: /** Specifies a page break before this paragraph. */ - void SetPageBreak(bool pageBreak = @true); + void SetPageBreak(bool pageBreak = true); /** Sets the spacing after a paragraph, in tenths of a millimetre. @@ -599,16 +593,13 @@ public: /** Sets the text effects, a bit list of styles. - The following styles can be passed: - Of these, only wxTEXT_ATTR_EFFECT_CAPITALS and wxTEXT_ATTR_EFFECT_STRIKETHROUGH are implemented. wxTEXT_ATTR_EFFECT_CAPITALS capitalises text when displayed (leaving the case of the actual buffer text unchanged), and wxTEXT_ATTR_EFFECT_STRIKETHROUGH draws a line through text. - To set effects, you should also pass wxTEXT_ATTR_EFFECTS to SetFlags(), and call SetTextEffectFlags() with the styles (taken from the above set) that you are interested in setting. @@ -622,7 +613,7 @@ public: generates a wxTextUrlEvent when the content is clicked. */ -#define void SetURL(const wxString& url) /* implementation is private */ + void SetURL(const wxString& url); /** Assignment from a wxTextAttr object. @@ -717,39 +708,31 @@ public: Constructor, creating and showing a text control. @param parent - Parent window. Should not be @NULL. - + Parent window. Should not be @NULL. @param id - Control identifier. A value of -1 denotes a default value. - + Control identifier. A value of -1 denotes a default value. @param value - Default text value. - + Default text value. @param pos - Text control position. - + Text control position. @param size - Text control size. - + Text control size. @param style - Window style. See wxTextCtrl. - + Window style. See wxTextCtrl. @param validator - Window validator. - + Window validator. @param name - Window name. + Window name. @remarks The horizontal scrollbar (wxHSCROLL style flag) will only be - created for multi-line text controls. Without a - horizontal scrollbar, text lines that don't fit in - the control's size will be wrapped (but no newline - character is inserted). Single line controls don't - have a horizontal scrollbar, the text is - automatically scrolled so that the insertion point is - always visible. + created for multi-line text controls. Without a + horizontal scrollbar, text lines that don't fit in the + control's size will be wrapped (but no newline + character is inserted). Single line controls don't have + a horizontal scrollbar, the text is automatically + scrolled so that the insertion point is always visible. - @sa Create(), wxValidator + @see Create(), wxValidator */ wxTextCtrl(); wxTextCtrl(wxWindow* parent, wxWindowID id, @@ -770,48 +753,44 @@ public: Appends the text to the end of the text control. @param text - Text to write to the text control. + Text to write to the text control. @remarks After the text is appended, the insertion point will be at the - end of the text control. If this behaviour is not - desired, the programmer should use GetInsertionPoint - and SetInsertionPoint. + end of the text control. If this behaviour is not + desired, the programmer should use GetInsertionPoint + and SetInsertionPoint. - @sa WriteText() + @see WriteText() */ void AppendText(const wxString& text); /** Call this function to enable auto-completion of the text typed in a single-line text control using the given @e choices. - Notice that currently this function is only implemented in wxGTK2 and wxMSW ports and does nothing under the other platforms. - This function is new since wxWidgets version 2.9.0 @returns @true if the auto-completion was enabled or @false if the - operation failed, typically because auto-completion - is not supported by the current platform. + operation failed, typically because auto-completion is + not supported by the current platform. - @sa AutoCompleteFileNames() + @see AutoCompleteFileNames() */ bool AutoComplete(const wxArrayString& choices); /** Call this function to enable auto-completion of the text typed in a single-line text control using all valid file system paths. - Notice that currently this function is only implemented in wxGTK2 port and does nothing under the other platforms. - This function is new since wxWidgets version 2.9.0 @returns @true if the auto-completion was enabled or @false if the - operation failed, typically because auto-completion - is not supported by the current platform. + operation failed, typically because auto-completion is + not supported by the current platform. - @sa AutoComplete() + @see AutoComplete() */ bool AutoCompleteFileNames(); @@ -848,23 +827,20 @@ public: Sets the text value and marks the control as not-modified (which means that IsModified() would return @false immediately after the call to SetValue). - Note that this function will not generate the @c wxEVT_COMMAND_TEXT_UPDATED event. This is the only difference with SetValue(). See @ref overview_progevent "this topic" for more information. - This function is new since wxWidgets version 2.7.1 @param value - The new value to set. It may contain newline characters if the text control is - multi-line. + The new value to set. It may contain newline characters if the text control + is multi-line. */ virtual void ChangeValue(const wxString& value); /** Clears the text in the control. - Note that this function will generate a @c wxEVT_COMMAND_TEXT_UPDATED event. */ @@ -891,7 +867,7 @@ public: /** Copies the selected text to the clipboard and removes the selection. */ -#define virtual void Cut() /* implementation is private */ + virtual void Cut(); /** Resets the internal 'modified' flag as if the current edits had been saved. @@ -901,21 +877,20 @@ public: /** This functions inserts into the control the character which would have been inserted if the given key event had occurred in the text control. The - @e event object should be the same as the one passed to @c EVT_KEY_DOWN + @a event object should be the same as the one passed to @c EVT_KEY_DOWN handler previously by wxWidgets. - Please note that this function doesn't currently work correctly for all keys under any platform but MSW. @returns @true if the event resulted in a change to the control, @false - otherwise. + otherwise. */ bool EmulateKeyPress(const wxKeyEvent& event); /** Returns the style currently used for the new text. - @sa SetDefaultStyle() + @see SetDefaultStyle() */ const wxTextAttr GetDefaultStyle(); @@ -925,7 +900,6 @@ public: the insertion point is at the end of the text control, it is equal to both GetValue().Length() and GetLastPosition(). - The following code snippet safely returns the character at the insertion point or the zero character if the point is at the end of the control. */ @@ -942,7 +916,7 @@ public: character(s). @param lineNo - Line number (starting from zero). + Line number (starting from zero). @returns The length of the line, or -1 if lineNo was invalid. */ @@ -953,7 +927,7 @@ public: any trailing newline character(s). @param lineNo - The line number, starting from zero. + The line number, starting from zero. @returns The contents of the line. */ @@ -963,16 +937,15 @@ public: Returns the number of lines in the text control buffer. @remarks Note that even empty text controls have one line (where the - insertion point is), so GetNumberOfLines() never - returns 0. + insertion point is), so GetNumberOfLines() never + returns 0. */ int GetNumberOfLines(); /** - Returns the string containing the text starting in the positions @e from and - up to @e to in the control. The positions must have been returned by another + Returns the string containing the text starting in the positions @a from and + up to @a to in the control. The positions must have been returned by another wxTextCtrl method. - Please note that the positions in a multiline wxTextCtrl do @b not correspond to the indices in the string returned by GetValue() because of the different new line @@ -985,7 +958,6 @@ public: /** Gets the current selection span. If the returned values are equal, there was no selection. - Please note that the indices returned may be used with the other wxTextctrl methods but don't necessarily represent the correct indices into the string returned by GetValue() for multiline controls @@ -994,10 +966,9 @@ public: text. @param from - The returned first position. - + The returned first position. @param to - The returned last position. + The returned last position. */ virtual void GetSelection(long* from, long* to); @@ -1012,9 +983,9 @@ public: support this function. @returns @true on success, @false if an error occurred - it may also mean - that the styles are not supported under this platform. + that the styles are not supported under this platform. - @sa SetStyle(), wxTextAttr + @see SetStyle(), wxTextAttr */ bool GetStyle(long position, wxTextAttr& style); @@ -1029,13 +1000,12 @@ public: /** This function finds the character at the specified position expressed in pixels. If the return code is not @c wxTE_HT_UNKNOWN the row and column - of the character closest to this position are returned in the @e col and - @e row parameters (unless the pointers are @NULL which is allowed). - + of the character closest to this position are returned in the @a col and + @a row parameters (unless the pointers are @NULL which is allowed). Please note that this function is currently only implemented in wxUniv, wxMSW and wxGTK2 ports. - @sa PositionToXY(), XYToPosition() + @see PositionToXY(), XYToPosition() */ wxTextCtrlHitTestResult HitTest(const wxPoint& pt, wxTextCoord col, @@ -1053,7 +1023,6 @@ public: Returns @true if the control is currently empty. This is the same as @c GetValue().empty() but can be much more efficient for the multiline controls containing big amounts of text. - This function is new since wxWidgets version 2.7.1 */ bool IsEmpty(); @@ -1062,7 +1031,7 @@ public: Returns @true if the text has been modified by user. Note that calling SetValue() doesn't make the control modified. - @sa MarkDirty() + @see MarkDirty() */ bool IsModified(); @@ -1070,7 +1039,7 @@ public: Returns @true if this is a multi line edit control and @false otherwise. - @sa IsSingleLine() + @see IsSingleLine() */ bool IsMultiLine(); @@ -1078,7 +1047,7 @@ public: Returns @true if this is a single line edit control and @false otherwise. - @sa @ref issingleline() IsMultiLine + @see @ref issingleline() IsMultiLine */ bool IsSingleLine(); @@ -1086,10 +1055,9 @@ public: Loads and displays the named file, if it exists. @param filename - The filename of the file to load. - + The filename of the file to load. @param fileType - The type of file to load. This is currently ignored in wxTextCtrl. + The type of file to load. This is currently ignored in wxTextCtrl. @returns @true if successful, @false otherwise. */ @@ -1099,7 +1067,7 @@ public: /** Mark text as modified (dirty). - @sa IsModified() + @see IsModified() */ void MarkDirty(); @@ -1108,11 +1076,11 @@ public: is to load the first dropped file into the control. @param event - The drop files event. + The drop files event. @remarks This is not implemented on non-Windows platforms. - @sa wxDropFilesEvent + @see wxDropFilesEvent */ void OnDropFiles(wxDropFilesEvent& event); @@ -1125,20 +1093,18 @@ public: Converts given position to a zero-based column, line number pair. @param pos - Position. - + Position. @param x - Receives zero based column number. - + Receives zero based column number. @param y - Receives zero based line number. + Receives zero based line number. @returns @true on success, @false on failure (most likely due to a too - large position parameter). + large position parameter). - @sa XYToPosition() + @see XYToPosition() */ - bool PositionToXY(long pos, long * x, long * y); + bool PositionToXY(long pos, long* x, long* y); /** If there is a redo facility and the last operation can be redone, redoes the @@ -1152,10 +1118,9 @@ public: the character at the last position. @param from - The first position. - + The first position. @param to - The last position. + The last position. */ virtual void Remove(long from, long to); @@ -1164,13 +1129,11 @@ public: the character at the last position with the given text. @param from - The first position. - + The first position. @param to - The last position. - + The last position. @param value - The value to replace the existing text with. + The value to replace the existing text with. */ virtual void Replace(long from, long to, const wxString& value); @@ -1178,10 +1141,9 @@ public: Saves the contents of the control in a text file. @param filename - The name of the file in which to save the text. - + The name of the file in which to save the text. @param fileType - The type of file to save. This is currently ignored in wxTextCtrl. + The type of file to save. This is currently ignored in wxTextCtrl. @returns @true if the operation was successful, @false otherwise. */ @@ -1192,23 +1154,21 @@ public: Changes the default style to use for the new text which is going to be added to the control using WriteText() or AppendText(). - If either of the font, foreground, or background colour is not set in @e style, the values of the previous default style are used for them. If the previous default style didn't set them neither, the global font or colours of the text control itself are used as fall back. - - However if the @e style parameter is the default wxTextAttr, then the + However if the @a style parameter is the default wxTextAttr, then the default style is just reset (instead of being combined with the new style which wouldn't change it at all). @param style - The style for the new text. + The style for the new text. @returns @true on success, @false if an error occurred - may also mean that - the styles are not supported under this platform. + the styles are not supported under this platform. - @sa GetDefaultStyle() + @see GetDefaultStyle() */ bool SetDefaultStyle(const wxTextAttr& style); @@ -1216,9 +1176,9 @@ public: Makes the text item editable or read-only, overriding the @b wxTE_READONLY flag. @param editable - If @true, the control is editable. If @false, the control is read-only. + If @true, the control is editable. If @false, the control is read-only. - @sa IsEditable() + @see IsEditable() */ virtual void SetEditable(const bool editable); @@ -1226,7 +1186,7 @@ public: Sets the insertion point at the given position. @param pos - Position to set. + Position to set. */ virtual void SetInsertionPoint(long pos); @@ -1240,17 +1200,14 @@ public: This function sets the maximum number of characters the user can enter into the control. In other words, it allows to limit the text value length to @e len not counting the terminating @c NUL character. - - If @e len is 0, the previously set max length limit, if any, is discarded + If @a len is 0, the previously set max length limit, if any, is discarded and the user may enter as much text as the underlying native text control widget supports (typically at least 32Kb). - If the user tries to enter more characters into the text control when it already is filled up to the maximal length, a @c wxEVT_COMMAND_TEXT_MAXLEN event is sent to notify the program about it (giving it the possibility to show an explanatory message, for example) and the extra input is discarded. - Note that under GTK+, this function may only be used with single line text controls. */ @@ -1259,7 +1216,7 @@ public: /** Marks the control as being modified by the user or not. - @sa MarkDirty(), DiscardEdits() + @see MarkDirty(), DiscardEdits() */ void SetModified(bool modified); @@ -1269,30 +1226,27 @@ public: in the control is selected. @param from - The first position. - + The first position. @param to - The last position. + The last position. */ virtual void SetSelection(long from, long to); /** - Changes the style of the given range. If any attribute within @e style is + Changes the style of the given range. If any attribute within @a style is not set, the corresponding attribute from GetDefaultStyle() is used. @param start - The start of the range to change. - + The start of the range to change. @param end - The end of the range to change. - + The end of the range to change. @param style - The new style for the range. + The new style for the range. @returns @true on success, @false if an error occurred - it may also mean - that the styles are not supported under this platform. + that the styles are not supported under this platform. - @sa GetStyle(), wxTextAttr + @see GetStyle(), wxTextAttr */ bool SetStyle(long start, long end, const wxTextAttr& style); @@ -1300,16 +1254,14 @@ public: Sets the text value and marks the control as not-modified (which means that IsModified() would return @false immediately after the call to SetValue). - Note that this function will generate a @c wxEVT_COMMAND_TEXT_UPDATED event. - This function is deprecated and should not be used in new code. Please use the ChangeValue() function instead. @param value - The new value to set. It may contain newline characters if the text control is - multi-line. + The new value to set. It may contain newline characters if the text control + is multi-line. */ virtual void SetValue(const wxString& value); @@ -1317,7 +1269,7 @@ public: Makes the line containing the given position visible. @param pos - The position that should be visible. + The position that should be visible. */ void ShowPosition(long pos); @@ -1332,12 +1284,12 @@ public: Writes the text into the text control at the current insertion position. @param text - Text to write to the text control. + Text to write to the text control. @remarks Newlines in the text string are the only control characters - allowed, and they will cause appropriate line breaks. - See () and AppendText() for more - convenient ways of writing to the window. + allowed, and they will cause appropriate line breaks. + See () and AppendText() for more + convenient ways of writing to the window. */ void WriteText(const wxString& text); @@ -1345,10 +1297,9 @@ public: Converts the given zero based column and line number to a position. @param x - The column number. - + The column number. @param y - The line number. + The line number. @returns The position value, or -1 if x or y was invalid. */ @@ -1410,16 +1361,15 @@ class wxStreamToTextRedirector { public: /** - The constructor starts redirecting output sent to @e ostr or @e cout for + The constructor starts redirecting output sent to @a ostr or @e cout for the default parameter value to the text control @e text. @param text - The text control to append output too, must be non-@NULL - + The text control to append output too, must be non-@NULL @param ostr - The C++ stream to redirect, cout is used if it is @NULL + The C++ stream to redirect, cout is used if it is @NULL */ - wxStreamToTextRedirector(wxTextCtrl text, ostream * ostr = @NULL); + wxStreamToTextRedirector(wxTextCtrl text, ostream* ostr = NULL); /** When a wxStreamToTextRedirector object is destroyed, the redirection is ended diff --git a/interface/textdlg.h b/interface/textdlg.h index 441d07f4d3..107da9c523 100644 --- a/interface/textdlg.h +++ b/interface/textdlg.h @@ -48,26 +48,22 @@ public: Constructor. Use ShowModal() to show the dialog. @param parent - Parent window. - + Parent window. @param message - Message to show on the dialog. - + Message to show on the dialog. @param defaultValue - The default value, which may be the empty string. - + The default value, which may be the empty string. @param style - A dialog style, specifying the buttons (wxOK, wxCANCEL) - and an optional wxCENTRE style. Additionally, wxTextCtrl styles (such as - wxTE_PASSWORD) may be specified here. - + A dialog style, specifying the buttons (wxOK, wxCANCEL) + and an optional wxCENTRE style. Additionally, wxTextCtrl styles (such as + wxTE_PASSWORD) may be specified here. @param pos - Dialog position. + Dialog position. */ wxTextEntryDialog(wxWindow* parent, const wxString& message, const wxString& caption = "Please enter text", const wxString& defaultValue = "", - long style = wxOK | wxCANCEL | wxCENTRE, + long style = wxOK | wxCANCEL | wxCENTRE, const wxPoint& pos = wxDefaultPosition); /** @@ -103,17 +99,16 @@ public: Pop up a dialog box with title set to @e caption, @e message, and a @e default_value. The user may type in text and press OK to return this text, or press Cancel to return the empty string. - - If @e centre is @true, the message text (which may include new line characters) + If @a centre is @true, the message text (which may include new line characters) is centred; if @false, the message is left-justified. */ wxString wxGetTextFromUser(const wxString& message, const wxString& caption = "Input text", const wxString& default_value = "", - wxWindow * parent = @NULL, + wxWindow* parent = NULL, int x = wxDefaultCoord, int y = wxDefaultCoord, - bool centre = @true); + bool centre = true); /** Similar to wxGetTextFromUser but the text entered @@ -123,8 +118,8 @@ wxString wxGetTextFromUser(const wxString& message, wxString wxGetPasswordFromUser(const wxString& message, const wxString& caption = "Input text", const wxString& default_value = "", - wxWindow * parent = @NULL, + wxWindow* parent = NULL, int x = wxDefaultCoord, int y = wxDefaultCoord, - bool centre = @true); + bool centre = true); diff --git a/interface/textfile.h b/interface/textfile.h index 1d19250651..24ee8ea6a9 100644 --- a/interface/textfile.h +++ b/interface/textfile.h @@ -94,7 +94,6 @@ public: Creates the file with the given name or the name which was given in the @ref ctor() constructor. The array of file lines is initially empty. - It will fail if the file already exists, Open() should be used in this case. */ @@ -105,7 +104,7 @@ public: /** Returns @true if the current line is the last one. */ -#define bool Eof() /* implementation is private */ + bool Eof(); /** Return @true if file exists - the name of the file should have been specified @@ -131,7 +130,7 @@ public: Apple Developer Tools) and wxTextFileType_Mac under Mac OS (including Mac OS X when compiling with CodeWarrior). */ -#define static const char* GetEOL(wxTextFileType type = typeDefault) /* implementation is private */ + static const char* GetEOL(wxTextFileType type = typeDefault); /** This method together with GetNextLine() @@ -148,7 +147,7 @@ public: wxString GetLastLine(); /** - Retrieves the line number @e n from the file. The returned line may be + Retrieves the line number @a n from the file. The returned line may be modified but you shouldn't add line terminator at the end - this will be done by wxTextFile. */ @@ -207,12 +206,10 @@ public: //@{ /** ) - Open() opens the file with the given name or the name which was given in the @ref ctor() constructor and also loads file in memory on success. It will fail if the file does not exist, Create() should be used in this case. - The @e conv argument is only meaningful in Unicode build of wxWidgets when it is used to convert the file to wide character representation. */ @@ -221,21 +218,18 @@ public: //@} /** - Delete line number @e n from the file. + Delete line number @a n from the file. */ void RemoveLine(size_t n); /** ) - - Change the file on disk. The @e typeNew parameter allows you to change the + Change the file on disk. The @a typeNew parameter allows you to change the file format (default argument means "don't change type") and may be used to convert, for example, DOS files to Unix. - The @e conv argument is only meaningful in Unicode build of wxWidgets when it is used to convert all lines to multibyte representation before writing them them to physical file. - Returns @true if operation succeeded, @false if it failed. */ bool Write(wxTextFileType typeNew = wxTextFileType_None); diff --git a/interface/tglbtn.h b/interface/tglbtn.h index ba1e1a501e..27e10963e7 100644 --- a/interface/tglbtn.h +++ b/interface/tglbtn.h @@ -16,7 +16,7 @@ This control emits an update UI event. @beginEventTable - @event{EVT_TOGGLEBUTTON(id\, func)}: + @event{EVT_TOGGLEBUTTON(id, func)}: Handles a toggle button click event. @endEventTable @@ -65,7 +65,7 @@ public: @c EVT_TOGGLEBUTTON event to be emitted. @param state - If @true, the button is pressed. + If @true, the button is pressed. */ void SetValue(bool state); }; @@ -85,7 +85,7 @@ public: controls sample. @beginEventTable - @event{EVT_TOGGLEBUTTON(id\, func)}: + @event{EVT_TOGGLEBUTTON(id, func)}: Handles a toggle button click event. @endEventTable @@ -104,32 +104,25 @@ public: Constructor, creating and showing a toggle button. @param parent - Parent window. Must not be @NULL. - + Parent window. Must not be @NULL. @param id - Toggle button identifier. The value wxID_ANY indicates a default value. - + Toggle button identifier. The value wxID_ANY indicates a default value. @param label - Text to be displayed next to the toggle button. - + Text to be displayed next to the toggle button. @param pos - Toggle button position. If wxDefaultPosition is specified then a default - position is chosen. - + Toggle button position. If wxDefaultPosition is specified then a + default position is chosen. @param size - Toggle button size. If wxDefaultSize is specified then a default - size is chosen. - + Toggle button size. If wxDefaultSize is specified then a + default size is chosen. @param style - Window style. See wxToggleButton. - + Window style. See wxToggleButton. @param validator - Window validator. - + Window validator. @param name - Window name. + Window name. - @sa Create(), wxValidator + @see Create(), wxValidator */ wxToggleButton(); wxToggleButton(wxWindow* parent, wxWindowID id, @@ -170,7 +163,7 @@ public: @c EVT_TOGGLEBUTTON event to be emitted. @param state - If @true, the button is pressed. + If @true, the button is pressed. */ void SetValue(bool state); }; diff --git a/interface/thread.h b/interface/thread.h index 98d51ae9e3..bfd661a200 100644 --- a/interface/thread.h +++ b/interface/thread.h @@ -40,9 +40,8 @@ class wxCondition { public: /** - Default and only constructor. The @e mutex must be locked by the caller + Default and only constructor. The @a mutex must be locked by the caller before calling Wait() function. - Use IsOk() to check if the object was successfully initialized. */ @@ -59,7 +58,7 @@ public: may be called whether the mutex associated with this condition is locked or not. - @sa Signal() + @see Signal() */ void Broadcast(); @@ -67,51 +66,47 @@ public: Returns @true if the object had been initialized successfully, @false if an error occurred. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** Signals the object waking up at most one thread. If several threads are waiting on the same condition, the exact thread which is woken up is undefined. If no threads are waiting, the signal is lost and the condition would have to be signalled again to wake up any thread which may start waiting on it later. - Note that this method may be called whether the mutex associated with this condition is locked or not. - @sa Broadcast() + @see Broadcast() */ void Signal(); /** Waits until the condition is signalled. - This method atomically releases the lock on the mutex associated with this condition (this is why it must be locked prior to calling Wait) and puts the thread to sleep until Signal() or Broadcast() is called. It then locks the mutex again and returns. - Note that even if Signal() had been called before Wait without waking up any thread, the thread would still wait for another one and so it is important to ensure that the condition will be signalled after Wait or the thread may sleep forever. @returns Returns wxCOND_NO_ERROR on success, another value if an error - occurred. + occurred. - @sa WaitTimeout() + @see WaitTimeout() */ wxCondError Wait(); /** Waits until the condition is signalled or the timeout has elapsed. - This method is identical to Wait() except that it returns, with the return code of @c wxCOND_TIMEOUT as soon as the given timeout expires. @param milliseconds - Timeout in milliseconds + Timeout in milliseconds */ wxCondError WaitTimeout(unsigned long milliseconds); }; @@ -165,7 +160,7 @@ class wxCriticalSectionLocker public: /** Constructs a wxCriticalSectionLocker object associated with given - @e criticalsection and enters it. + @a criticalsection and enters it. */ wxCriticalSectionLocker(wxCriticalSection& criticalsection); @@ -239,11 +234,9 @@ public: /** This is the entry point of the thread. This function is pure virtual and must be implemented by any derived class. The thread execution will start here. - The returned value is the thread exit code which is only useful for joinable threads and is the value returned by @ref wxThread::wait GetThread()-Wait. - This function is called by wxWidgets itself and should never be called directly. */ @@ -253,11 +246,10 @@ public: This is a public function that returns the wxThread object associated with the thread. */ - wxThread * GetThread(); + wxThread* GetThread(); /** wxThread * m_thread - the actual wxThread object. */ }; @@ -347,18 +339,14 @@ public: object. It does not create or start execution of the real thread -- for this you should use the Create() and Run() methods. - - The possible values for @e kind parameters are: - + The possible values for @a kind parameters are: @b wxTHREAD_DETACHED - Creates a detached thread. @b wxTHREAD_JOINABLE - Creates a joinable thread. */ wxThread(wxThreadKind kind = wxTHREAD_DETACHED); @@ -369,7 +357,6 @@ public: Delete() on it or wait until it terminates (and auto destructs) itself. Because the detached threads delete themselves, they can only be allocated on the heap. - Joinable threads should be deleted explicitly. The Delete() and Kill() functions will not delete the C++ thread object. It is also safe to allocate them on stack. @@ -384,7 +371,6 @@ public: support setting it explicitly, eg. Unix system without @c pthread_attr_setstacksize). If you do not specify the stack size, the system's default value is used. - @b Warning: It is a good idea to explicitly specify a value as systems' default values vary from just a couple of KB on some systems (BSD and OS/2 systems) to one or several MB (Windows, Solaris, Linux). So, if you @@ -405,11 +391,9 @@ public: Calling Delete() gracefully terminates a detached thread, either when the thread calls TestDestroy() or finished processing. - (Note that while this could work on a joinable thread you simply should not call this routine on one as afterwards you may not be able to call Wait() to free the memory of that thread). - See @ref overview_deletionwxthread "wxThread deletion" for a broader explanation of this routine. */ @@ -422,7 +406,6 @@ public: application has run into problems because the thread is using the default behavior and has already deleted itself. Naturally, they instead attempt to use joinable threads in place of the previous behavior. - However, polling a wxThread for when it has ended is in general a bad idea - in fact calling a routine on any running wxThread should be avoided if possible. Instead, find a way to notify yourself when the thread has ended. @@ -439,10 +422,8 @@ public: /** This is the entry point of the thread. This function is pure virtual and must be implemented by any derived class. The thread execution will start here. - The returned value is the thread exit code which is only useful for joinable threads and is the value returned by Wait(). - This function is called by wxWidgets itself and should never be called directly. */ @@ -452,7 +433,6 @@ public: This is a protected function of the wxThread class and thus can only be called from a derived class. It also can only be called in the context of this thread, i.e. a thread can only exit from itself, not from another thread. - This function will terminate the OS thread (i.e. stop the associated path of execution) and also delete the associated C++ object for detached threads. OnExit() will be called just before exiting. @@ -462,7 +442,7 @@ public: /** Returns the number of system CPUs or -1 if the value is unknown. - @sa SetConcurrency() + @see SetConcurrency() */ static int GetCPUCount(); @@ -483,30 +463,24 @@ public: /** Gets the priority of the thread, between zero and 100. - The following priorities are defined: - @b WXTHREAD_MIN_PRIORITY - 0 @b WXTHREAD_DEFAULT_PRIORITY - 50 @b WXTHREAD_MAX_PRIORITY - 100 */ int GetPriority(); /** Returns @true if the thread is alive (i.e. started and not terminating). - Note that this function can only safely be used with joinable threads, not detached ones as the latter delete themselves and so when the real thread is no longer alive, it is not possible to call this function because @@ -533,7 +507,6 @@ public: /** Returns @true if the thread is running. - This method may only be safely used for joinable threads, see the remark in IsAlive(). */ @@ -546,16 +519,13 @@ public: allocated to the thread will not be freed and the state of the C runtime library may become inconsistent. Use Delete() for detached threads or Wait() for joinable threads instead. - For detached threads Kill() will also delete the associated C++ object. However this will not happen for joinable threads and this means that you will still have to delete the wxThread object yourself to avoid memory leaks. In neither case OnExit() of the dying thread will be called, so no thread-specific cleanup will be performed. - This function can only be called from another thread context, i.e. a thread cannot kill itself. - It is also an error to call this function for a thread which is not running or paused (in the latter case, the thread will be resumed first) -- if you do it, a @c wxTHREAD_NOT_RUNNING error will be returned. @@ -567,7 +537,6 @@ public: thread associated with the wxThread object, not in the context of the main thread. This function will not be called if the thread was @ref kill() killed. - This function should never be called directly. */ void OnExit(); @@ -577,14 +546,12 @@ public: suspended immediately, under others it will only be suspended when it calls TestDestroy() for the next time (hence, if the thread doesn't call it at all, it won't be suspended). - This function can only be called from another thread context. */ wxThreadError Pause(); /** Resumes a thread suspended by the call to Pause(). - This function can only be called from another thread context. */ wxThreadError Resume(); @@ -592,16 +559,14 @@ public: /** Starts the thread execution. Should be called after Create(). - This function can only be called from another thread context. */ -#define wxThreadError Run() /* implementation is private */ + wxThreadError Run(); /** Sets the thread concurrency level for this process. This is, roughly, the number of threads that the system tries to schedule to run in parallel. - The value of 0 for @e level may be used to set the default one. - + The value of 0 for @a level may be used to set the default one. Returns @true on success or @false otherwise (for example, if this function is not implemented for this platform -- currently everything except Solaris). */ @@ -611,30 +576,24 @@ public: Sets the priority of the thread, between 0 and 100. It can only be set after calling Create() but before calling Run(). - The following priorities are already defined: - @b WXTHREAD_MIN_PRIORITY - 0 @b WXTHREAD_DEFAULT_PRIORITY - 50 @b WXTHREAD_MAX_PRIORITY - 100 */ void SetPriority(int priority); /** Pauses the thread execution for the given amount of time. - This function should be used instead of wxSleep by all worker threads (i.e. all except the main one). */ @@ -644,7 +603,6 @@ public: This function should be called periodically by the thread to ensure that calls to Pause() and Delete() will work. If it returns @true, the thread should exit as soon as possible. - Notice that under some platforms (POSIX), implementation of Pause() also relies on this function being called, so not calling it would prevent both stopping and suspending thread from working. @@ -661,13 +619,12 @@ public: a thread is undefined. */ - static wxThread * This(); + static wxThread* This(); /** There are two types of threads in wxWidgets: @e detached and @e joinable, modeled after the the POSIX thread API. This is different from the Win32 API where all threads are joinable. - By default wxThreads in wxWidgets use the detached behavior. Detached threads delete themselves once they have completed, either by themselves when they complete @@ -679,7 +636,6 @@ public: are safe to create on the stack. Joinable threads also provide the ability for one to get value it returned from Entry() through Wait(). - You shouldn't hurry to create all the threads joinable, however, because this has a disadvantage as well: you @b must Wait() for a joinable thread or the system resources used by it will never be freed, and you also must delete the @@ -697,11 +653,8 @@ public: error. Notice that, unlike Delete() doesn't cancel the thread in any way so the caller waits for as long as it takes to the thread to exit. - You can only Wait() for joinable (not detached) threads. - This function can only be called from another thread context. - See @ref overview_deletionwxthread "wxThread deletion" for a broader explanation of this routine. */ @@ -744,7 +697,6 @@ public: a joinable thread on the heap, remember to delete it manually with the delete operator or similar means as only detached threads handle this type of memory management. - Since detached threads delete themselves when they are finished processing, you should take care when calling a routine on one. If you are certain the thread is still running and would like to end it, you may call @@ -752,17 +704,14 @@ public: that the thread will be deleted after that call to Delete()). It should be implied that you should never attempt to delete a detached thread with the delete operator or similar means. - As mentioned, Wait() or Delete() attempts to gracefully terminate a joinable and detached thread, respectively. It does this by waiting until the thread in question calls TestDestroy() or ends processing (returns from wxThread::Entry). - Obviously, if the thread does call TestDestroy() and does not end the calling thread will come to halt. This is why it is important to call TestDestroy() in the Entry() routine of your threads as often as possible. - As a last resort you can end the thread immediately through Kill(). It is strongly recommended that you do not do this, however, as it does not free the resources associated with @@ -776,13 +725,11 @@ public: wxApp::OnInit or your main function runs in, for example) are considered "secondary threads". These include all threads created by Create() or the corresponding constructors. - GUI calls, such as those to a wxWindow or wxBitmap are explicitly not safe at all in secondary threads and could end your application prematurely. This is due to several reasons, including the underlying native API and the fact that wxThread does not run a GUI event loop similar to other APIs as MFC. - A workaround that works on some wxWidgets ports is calling wxMutexGUIEnter before any GUI calls and then calling wxMutexGUILeave afterwords. However, the recommended way is to simply process the GUI calls in the main thread @@ -822,13 +769,12 @@ class wxSemaphore { public: /** - Specifying a @e maxcount of 0 actually makes wxSemaphore behave as if + Specifying a @a maxcount of 0 actually makes wxSemaphore behave as if there is no upper limit. If maxcount is 1, the semaphore behaves almost as a mutex (but unlike a mutex it can be released by a thread different from the one which acquired it). - - @e initialcount is the initial value of the semaphore which must be between - 0 and @e maxcount (if it is not set to 0). + @a initialcount is the initial value of the semaphore which must be between + 0 and @a maxcount (if it is not set to 0). */ wxSemaphore(int initialcount = 0, int maxcount = 0); @@ -898,7 +844,7 @@ public: /** Returns @true if mutex was acquired in the constructor, @false otherwise. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); }; @@ -990,6 +936,7 @@ bool wxIsMainThread(); wxCRIT_SECT_LOCKER: it creates a static critical section object and also the lock object associated with it. Because of this, it can be only used inside a function, not at global scope. For example: + @code int IncCount() { @@ -1009,7 +956,7 @@ bool wxIsMainThread(); #define wxCRITICAL_SECTION(name) /* implementation is private */ /** - This macro declares a critical section object named @e cs if + This macro declares a critical section object named @a cs if @c wxUSE_THREADS is 1 and does nothing if it is 0. As it doesn't include the @c static keyword (unlike wxCRIT_SECT_DECLARE), it can be used to declare @@ -1023,8 +970,8 @@ bool wxIsMainThread(); of the calling thread until the main thread (or any other thread holding the main GUI lock) leaves the GUI library and no other thread will enter the GUI library until the calling thread calls ::wxMutexGuiLeave. - Typically, these functions are used like this: + @code void MyThread::Foo(void) { @@ -1042,14 +989,13 @@ bool wxIsMainThread(); Note that under GTK, no creation of top-level windows is allowed in any thread but the main one. - This function is only defined on platforms which support preemptive threads. */ void wxMutexGuiEnter(); /** - This macro declares a (static) critical section object named @e cs if + This macro declares a (static) critical section object named @a cs if @c wxUSE_THREADS is 1 and does nothing if it is 0. */ #define wxCRIT_SECT_DECLARE(cs) /* implementation is private */ @@ -1063,10 +1009,10 @@ void wxMutexGuiEnter(); /** This macro creates a @ref overview_wxcriticalsectionlocker "critical section lock" - object named @e name and associated with the critical section @e cs if + object named @a name and associated with the critical section @a cs if @c wxUSE_THREADS is 1 and does nothing if it is 0. */ -#define wxCRIT_SECT_LOCKER(name, cs) /* implementation is private */ +#define wxCRIT_SECT_LOCKER(name, cs) /* implementation is private */ /** This macro is equivalent to @ref wxCriticalSection::enter cs.Enter if diff --git a/interface/timer.h b/interface/timer.h index a29aa8efae..d9f99ec7b4 100644 --- a/interface/timer.h +++ b/interface/timer.h @@ -49,7 +49,7 @@ public: SetOwner() for the description of parameters. */ wxTimer(); - wxTimer(wxEvtHandler * owner, int id = -1); + wxTimer(wxEvtHandler* owner, int id = -1); //@} /** @@ -88,43 +88,38 @@ public: /** This member should be overridden by the user if the default constructor was used and SetOwner() wasn't called. - Perform whatever action which is to be taken periodically here. */ void Notify(); /** - Associates the timer with the given @e owner object. When the timer is + Associates the timer with the given @a owner object. When the timer is running, the owner will receive @ref overview_wxtimerevent "timer events" with - id equal to @e id specified here. + id equal to @a id specified here. */ - void SetOwner(wxEvtHandler * owner, int id = -1); + void SetOwner(wxEvtHandler* owner, int id = -1); /** - (Re)starts the timer. If @e milliseconds parameter is -1 (value by default), + (Re)starts the timer. If @a milliseconds parameter is -1 (value by default), the previous value is used. Returns @false if the timer could not be started, @true otherwise (in MS Windows timers are a limited resource). - - If @e oneShot is @false (the default), the Notify() + If @a oneShot is @false (the default), the Notify() function will be called repeatedly until the timer is stopped. If @true, it will be called only once and the timer will stop automatically. To make your code more readable you may also use the following symbolic constants: - wxTIMER_CONTINUOUS - Start a normal, continuously running, timer wxTIMER_ONE_SHOT - Start a one shot timer If the timer was already running, it will be stopped by this method before restarting it. */ - bool Start(int milliseconds = -1, bool oneShot = @false); + bool Start(int milliseconds = -1, bool oneShot = false); /** Stops the timer. diff --git a/interface/tipdlg.h b/interface/tipdlg.h index 9dff0384dd..bce84c8837 100644 --- a/interface/tipdlg.h +++ b/interface/tipdlg.h @@ -32,14 +32,13 @@ public: Constructor. @param currentTip - The starting tip index. + The starting tip index. */ wxTipProvider(size_t currentTip); /** Returns the index of the current tip (i.e. the one which would be returned by GetTip). - The program usually remembers the value returned by this function after calling wxShowTip. Note that it is not the same as the value which was passed to wxShowTip + 1 because the user might have pressed the "Next" @@ -75,14 +74,13 @@ public: used with wxShowTip. @param filename - The name of the file containing the tips, one per line - + The name of the file containing the tips, one per line @param currentTip - The index of the first tip to show - normally this index - is remembered between the 2 program runs. + The index of the first tip to show - normally this index + is remembered between the 2 program runs. - @sa @ref overview_tipsoverview "Tips overview" + @see @ref overview_tipsoverview "Tips overview" */ -wxTipProvider * wxCreateFileTipProvider(const wxString& filename, - size_t currentTip); +wxTipProvider* wxCreateFileTipProvider(const wxString& filename, + size_t currentTip); diff --git a/interface/tipwin.h b/interface/tipwin.h index 75b3fa5dcd..b6b6d29b61 100644 --- a/interface/tipwin.h +++ b/interface/tipwin.h @@ -28,41 +28,36 @@ public: Constructor. The tip is shown immediately after the window is constructed. @param parent - The parent window, must be non-@NULL - + The parent window, must be non-@NULL @param text - The text to show, may contain the new line characters - + The text to show, may contain the new line characters @param maxLength - The length of each line, in pixels. Set to a very large - value to avoid wrapping lines - + The length of each line, in pixels. Set to a very large + value to avoid wrapping lines @param windowPtr - Simply passed to - SetTipWindowPtr below, please see its - documentation for the description of this parameter - + Simply passed to + SetTipWindowPtr below, please see its + documentation for the description of this parameter @param rectBounds - If non-@NULL, passed to - SetBoundingRect below, please see its - documentation for the description of this parameter + If non-@NULL, passed to + SetBoundingRect below, please see its + documentation for the description of this parameter */ wxTipWindow(wxWindow* parent, const wxString& text, wxCoord maxLength = 100, wxTipWindow** windowPtr, - wxRect * rectBounds = @NULL); + wxRect* rectBounds = NULL); /** By default, the tip window disappears when the user clicks the mouse or presses a keyboard key or if it loses focus in any other way - for example because the user switched to another application window. - - Additionally, if a non-empty @e rectBound is provided, the tip window will + Additionally, if a non-empty @a rectBound is provided, the tip window will also automatically close if the mouse leaves this area. This is useful to dismiss the tip mouse when the mouse leaves the object it is associated with. @param rectBound - The bounding rectangle for the mouse in the screen coordinates + The bounding rectangle for the mouse in the screen coordinates */ void SetBoundingRect(const wxRect& rectBound); diff --git a/interface/tokenzr.h b/interface/tokenzr.h index 5d8668ecae..6250d27dc0 100644 --- a/interface/tokenzr.h +++ b/interface/tokenzr.h @@ -130,7 +130,6 @@ public: GetNextToken() or @c NUL if there had been no calls to this function yet or if it returned the trailing empty token in @c wxTOKEN_RET_EMPTY_ALL mode. - This function is new since wxWidgets version 2.7.0 */ wxChar GetLastDelimiter(); @@ -159,7 +158,6 @@ public: /** Initializes the tokenizer. - Pass the string to tokenize, a string containing delimiters, and the mode specifying how the string should be tokenized. */ diff --git a/interface/toolbar.h b/interface/toolbar.h index 33cb1efe97..ce44a080fe 100644 --- a/interface/toolbar.h +++ b/interface/toolbar.h @@ -66,37 +66,33 @@ public: Constructs a toolbar. @param parent - Pointer to a parent window. - + Pointer to a parent window. @param id - Window identifier. If -1, will automatically create an identifier. - + Window identifier. If -1, will automatically create an identifier. @param pos - Window position. wxDefaultPosition is (-1, -1) which indicates that wxWidgets - should generate a default position for the window. If using the wxWindow class - directly, supply - an actual position. - + Window position. wxDefaultPosition is (-1, -1) which indicates that + wxWidgets + should generate a default position for the window. If using the wxWindow + class directly, supply + an actual position. @param size - Window size. wxDefaultSize is (-1, -1) which indicates that wxWidgets - should generate a default size for the window. - + Window size. wxDefaultSize is (-1, -1) which indicates that wxWidgets + should generate a default size for the window. @param style - Window style. See wxToolBar for details. - + Window style. See wxToolBar for details. @param name - Window name. + Window name. @remarks After a toolbar is created, you use AddTool() and - perhaps AddSeparator(), and then you must - call Realize() to construct and display the - toolbar tools. + perhaps AddSeparator(), and then you must call + Realize() to construct and display the toolbar + tools. */ wxToolBar(); wxToolBar(wxWindow* parent, wxWindowID id, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, - long style = wxTB_HORIZONTAL | wxBORDER_NONE, + long style = wxTB_HORIZONTAL | wxBORDER_NONE, const wxString& name = wxPanelNameStr); //@} @@ -109,7 +105,7 @@ public: Adds a new check (or toggle) tool to the toolbar. The parameters are the same as in AddTool(). - @sa AddTool() + @see AddTool() */ wxToolBarToolBase* AddCheckTool(int toolId, const wxString& label, @@ -117,19 +113,18 @@ public: const wxBitmap& bitmap2, const wxString& shortHelpString = "", const wxString& longHelpString = "", - wxObject* clientData = @NULL); + wxObject* clientData = NULL); /** Adds any control to the toolbar, typically e.g. a combobox. @param control - The control to be added. - + The control to be added. @param label - Text to be displayed near the control. + Text to be displayed near the control. @remarks wxMSW: the label is only displayed if there is enough space - available below the embedded control. + available below the embedded control. */ bool AddControl(wxControl* control, const wxString label = ""); @@ -139,11 +134,10 @@ public: other words whenever a button in the group is pressed the previously pressed button is automatically released. You should avoid having the radio groups of only one element as it would be impossible for the user to use such button. - By default, the first button in the radio group is initially pressed, the others are not. - @sa AddTool() + @see AddTool() */ wxToolBarToolBase* AddRadioTool(int toolId, const wxString& label, @@ -151,12 +145,12 @@ public: const wxBitmap& bitmap2, const wxString& shortHelpString = "", const wxString& longHelpString = "", - wxObject* clientData = @NULL); + wxObject* clientData = NULL); /** Adds a separator for spacing groups of tools. - @sa AddTool(), SetToolSeparation() + @see AddTool(), SetToolSeparation() */ void AddSeparator(); @@ -168,43 +162,37 @@ public: you to add an existing tool. @param toolId - An integer by which - the tool may be identified in subsequent operations. - + An integer by which + the tool may be identified in subsequent operations. @param kind - May be wxITEM_NORMAL for a normal button (default), - wxITEM_CHECK for a checkable tool (such tool stays pressed after it had been - toggled) or wxITEM_RADIO for a checkable tool which makes part of a radio - group of tools each of which is automatically unchecked whenever another button - in the group is checked - + May be wxITEM_NORMAL for a normal button (default), + wxITEM_CHECK for a checkable tool (such tool stays pressed after it had been + toggled) or wxITEM_RADIO for a checkable tool which makes part of a radio + group of tools each of which is automatically unchecked whenever another + button + in the group is checked @param bitmap1 - The primary tool bitmap. - + The primary tool bitmap. @param bitmap2 - The bitmap used when the tool is disabled. If it is equal to - wxNullBitmap, the disabled bitmap is automatically generated by greing the - normal one. - + The bitmap used when the tool is disabled. If it is equal to + wxNullBitmap, the disabled bitmap is automatically generated by greing the + normal one. @param shortHelpString - This string is used for the tools tooltip - + This string is used for the tools tooltip @param longHelpString - This string is shown in the statusbar (if any) of the - parent frame when the mouse pointer is inside the tool - + This string is shown in the statusbar (if any) of the + parent frame when the mouse pointer is inside the tool @param clientData - An optional pointer to client data which can be - retrieved later using GetToolClientData(). - + An optional pointer to client data which can be + retrieved later using GetToolClientData(). @param tool - The tool to be added. + The tool to be added. @remarks After you have added tools to a toolbar, you must call - Realize() in order to have the tools appear. + Realize() in order to have the tools appear. - @sa AddSeparator(), AddCheckTool(), AddRadioTool(), - InsertTool(), DeleteTool(), Realize() + @see AddSeparator(), AddCheckTool(), AddRadioTool(), + InsertTool(), DeleteTool(), Realize() */ wxToolBarToolBase* AddTool(int toolId, const wxString& label, const wxBitmap& bitmap1, @@ -216,7 +204,7 @@ public: wxItemKind kind = wxITEM_NORMAL, const wxString& shortHelpString = "", const wxString& longHelpString = "", - wxObject* clientData = @NULL); + wxObject* clientData = NULL); wxToolBarToolBase* AddTool(wxToolBarToolBase* tool); //@} @@ -229,13 +217,11 @@ public: Removes the specified tool from the toolbar and deletes it. If you don't want to delete the tool, but just to remove it from the toolbar (to possibly add it back later), you may use RemoveTool() instead. - Note that it is unnecessary to call Realize() for the change to take place, it will happen immediately. - Returns @true if the tool was deleted, @false otherwise. - @sa DeleteToolByPos() + @see DeleteToolByPos() */ bool DeleteTool(int toolId); @@ -249,26 +235,25 @@ public: Enables or disables the tool. @param toolId - Tool to enable or disable. - + Tool to enable or disable. @param enable - If @true, enables the tool, otherwise disables it. + If @true, enables the tool, otherwise disables it. @remarks Some implementations will change the visible state of the tool - to indicate that it is disabled. + to indicate that it is disabled. - @sa GetToolEnabled(), ToggleTool() + @see GetToolEnabled(), ToggleTool() */ void EnableTool(int toolId, bool enable); /** - Returns a pointer to the tool identified by @e id or + Returns a pointer to the tool identified by @a id or @NULL if no corresponding tool is found. */ wxToolBarToolBase* FindById(int id); /** - Returns a pointer to the control identified by @e id or + Returns a pointer to the control identified by @a id or @NULL if no corresponding control is found. */ wxControl* FindControl(int id); @@ -277,10 +262,9 @@ public: Finds a tool for the given mouse position. @param x - X position. - + X position. @param y - Y position. + Y position. @returns A pointer to a tool if a tool is found, or @NULL otherwise. @@ -292,7 +276,7 @@ public: Returns the left/right and top/bottom margins, which are also used for inter-toolspacing. - @sa SetMargins() + @see SetMargins() */ wxSize GetMargins(); @@ -301,10 +285,10 @@ public: size is 16 by 15 pixels. @remarks Note that this is the size of the bitmap you pass to - AddTool(), and not the eventual size of the - tool button. + AddTool(), and not the eventual size of the + tool button. - @sa SetToolBitmapSize(), GetToolSize() + @see SetToolBitmapSize(), GetToolSize() */ wxSize GetToolBitmapSize(); @@ -312,7 +296,7 @@ public: Get any client data associated with the tool. @param toolId - Id of the tool, as passed to AddTool(). + Id of the tool, as passed to AddTool(). @returns Client data, or @NULL if there is none. */ @@ -322,11 +306,11 @@ public: Called to determine whether a tool is enabled (responds to user input). @param toolId - Id of the tool in question. + Id of the tool in question. @returns @true if the tool is enabled, @false otherwise. - @sa EnableTool() + @see EnableTool() */ bool GetToolEnabled(int toolId); @@ -334,16 +318,16 @@ public: Returns the long help for the given tool. @param toolId - The tool in question. + The tool in question. - @sa SetToolLongHelp(), SetToolShortHelp() + @see SetToolLongHelp(), SetToolShortHelp() */ wxString GetToolLongHelp(int toolId); /** Returns the value used for packing tools. - @sa SetToolPacking() + @see SetToolPacking() */ int GetToolPacking(); @@ -356,7 +340,7 @@ public: /** Returns the default separator size. - @sa SetToolSeparation() + @see SetToolSeparation() */ int GetToolSeparation(); @@ -364,9 +348,9 @@ public: Returns the short help for the given tool. @param toolId - The tool in question. + The tool in question. - @sa GetToolLongHelp(), SetToolShortHelp() + @see GetToolLongHelp(), SetToolShortHelp() */ wxString GetToolShortHelp(int toolId); @@ -375,7 +359,7 @@ public: because of added 3D effects. - @sa SetToolBitmapSize(), GetToolBitmapSize() + @see SetToolBitmapSize(), GetToolBitmapSize() */ wxSize GetToolSize(); @@ -383,11 +367,11 @@ public: Gets the on/off state of a toggle tool. @param toolId - The tool in question. + The tool in question. @returns @true if the tool is toggled on, @false otherwise. - @sa ToggleTool() + @see ToggleTool() */ bool GetToolState(int toolId); @@ -398,105 +382,94 @@ public: /** Inserts the control into the toolbar at the given position. - You must call Realize() for the change to take place. - @sa AddControl(), InsertTool() + @see AddControl(), InsertTool() */ - wxToolBarToolBase * InsertControl(size_t pos, - wxControl * control); + wxToolBarToolBase* InsertControl(size_t pos, wxControl* control); /** Inserts the separator into the toolbar at the given position. - You must call Realize() for the change to take place. - @sa AddSeparator(), InsertTool() + @see AddSeparator(), InsertTool() */ - wxToolBarToolBase * InsertSeparator(size_t pos); + wxToolBarToolBase* InsertSeparator(size_t pos); //@{ /** Inserts the tool with the specified attributes into the toolbar at the given position. - You must call Realize() for the change to take place. - @sa AddTool(), InsertControl(), InsertSeparator() - */ - wxToolBarToolBase * InsertTool(size_t pos, int toolId, - const wxBitmap& bitmap1, - const wxBitmap& bitmap2 = wxNullBitmap, - bool isToggle = @false, - wxObject* clientData = @NULL, - const wxString& shortHelpString = "", - const wxString& longHelpString = ""); - wxToolBarToolBase * InsertTool(size_t pos, - wxToolBarToolBase* tool); + @see AddTool(), InsertControl(), InsertSeparator() + */ + wxToolBarToolBase* InsertTool(size_t pos, int toolId, + const wxBitmap& bitmap1, + const wxBitmap& bitmap2 = wxNullBitmap, + bool isToggle = false, + wxObject* clientData = NULL, + const wxString& shortHelpString = "", + const wxString& longHelpString = ""); + wxToolBarToolBase* InsertTool(size_t pos, + wxToolBarToolBase* tool); //@} /** Called when the user clicks on a tool with the left mouse button. - This is the old way of detecting tool clicks; although it will still work, you should use the EVT_MENU or EVT_TOOL macro instead. @param toolId - The identifier passed to AddTool(). - + The identifier passed to AddTool(). @param toggleDown - @true if the tool is a toggle and the toggle is down, otherwise is @false. + @true if the tool is a toggle and the toggle is down, otherwise is @false. @returns If the tool is a toggle and this function returns @false, the - toggle toggle state (internal and visual) will not be - changed. This provides a way of specifying that - toggle operations are not permitted in some - circumstances. + toggle toggle state (internal and visual) will not be + changed. This provides a way of specifying that toggle + operations are not permitted in some circumstances. - @sa OnMouseEnter(), OnRightClick() + @see OnMouseEnter(), OnRightClick() */ bool OnLeftClick(int toolId, bool toggleDown); /** This is called when the mouse cursor moves into a tool or out of the toolbar. - This is the old way of detecting mouse enter events; although it will still work, you should use the EVT_TOOL_ENTER macro instead. @param toolId - Greater than -1 if the mouse cursor has moved into the tool, - or -1 if the mouse cursor has moved. The - programmer can override this to provide extra information about the tool, - such as a short description on the status line. + Greater than -1 if the mouse cursor has moved into the tool, + or -1 if the mouse cursor has moved. The + programmer can override this to provide extra information about the tool, + such as a short description on the status line. @remarks With some derived toolbar classes, if the mouse moves quickly - out of the toolbar, wxWidgets may not be able to - detect it. Therefore this function may not always be - called when expected. + out of the toolbar, wxWidgets may not be able to detect + it. Therefore this function may not always be called + when expected. */ void OnMouseEnter(int toolId); /** Called when the user clicks on a tool with the right mouse button. The programmer should override this function to detect right tool clicks. - This is the old way of detecting tool right clicks; although it will still work, you should use the EVT_TOOL_RCLICKED macro instead. @param toolId - The identifier passed to AddTool(). - + The identifier passed to AddTool(). @param x - The x position of the mouse cursor. - + The x position of the mouse cursor. @param y - The y position of the mouse cursor. + The y position of the mouse cursor. @remarks A typical use of this member might be to pop up a menu. - @sa OnMouseEnter(), OnLeftClick() + @see OnMouseEnter(), OnLeftClick() */ void OnRightClick(int toolId, float x, float y); @@ -508,13 +481,12 @@ public: /** Removes the given tool from the toolbar but doesn't delete it. This allows to insert/add this tool back to this (or another) toolbar later. - Note that it is unnecessary to call Realize() for the change to take place, it will happen immediately. - @sa DeleteTool() + @see DeleteTool() */ - wxToolBarToolBase * RemoveTool(int id); + wxToolBarToolBase* RemoveTool(int id); /** Sets the bitmap resource identifier for specifying tool bitmaps as indices @@ -525,7 +497,6 @@ public: /** Sets the dropdown menu for the tool given by its @e id. The tool itself will delete the menu when it's no longer needed. - If you define a EVT_TOOL_DROPDOWN handler in your program, you must call wxEvent::Skip from it or the menu won't be displayed. */ @@ -536,19 +507,17 @@ public: Set the values to be used as margins for the toolbar. @param size - Margin size. - + Margin size. @param x - Left margin, right margin and inter-tool separation value. - + Left margin, right margin and inter-tool separation value. @param y - Top margin, bottom margin and inter-tool separation value. + Top margin, bottom margin and inter-tool separation value. @remarks This must be called before the tools are added if absolute - positioning is to be used, and the default - (zero-size) margins are to be overridden. + positioning is to be used, and the default (zero-size) + margins are to be overridden. - @sa GetMargins(), wxSize + @see GetMargins(), wxSize */ void SetMargins(const wxSize& size); void SetMargins(int x, int y); @@ -559,12 +528,12 @@ public: pixels. @param size - The size of the bitmaps in the toolbar. + The size of the bitmaps in the toolbar. @remarks This should be called to tell the toolbar what the tool bitmap - size is. Call it before you add tools. + size is. Call it before you add tools. - @sa GetToolBitmapSize(), GetToolSize() + @see GetToolBitmapSize(), GetToolSize() */ void SetToolBitmapSize(const wxSize& size); @@ -586,15 +555,14 @@ public: Sets the long help for the given tool. @param toolId - The tool in question. - + The tool in question. @param helpString - A string for the long help. + A string for the long help. @remarks You might use the long help for displaying the tool purpose on - the status line. + the status line. - @sa GetToolLongHelp(), SetToolShortHelp(), + @see GetToolLongHelp(), SetToolShortHelp(), */ void SetToolLongHelp(int toolId, const wxString& helpString); @@ -608,13 +576,13 @@ public: Sets the value used for spacing tools. The default value is 1. @param packing - The value for packing. + The value for packing. @remarks The packing is used for spacing in the vertical direction if the - toolbar is horizontal, and for spacing in the - horizontal direction if the toolbar is vertical. + toolbar is horizontal, and for spacing in the + horizontal direction if the toolbar is vertical. - @sa GetToolPacking() + @see GetToolPacking() */ void SetToolPacking(int packing); @@ -622,9 +590,9 @@ public: Sets the default separator size. The default value is 5. @param separation - The separator size. + The separator size. - @sa AddSeparator() + @see AddSeparator() */ void SetToolSeparation(int separation); @@ -632,15 +600,14 @@ public: Sets the short help for the given tool. @param toolId - The tool in question. - + The tool in question. @param helpString - The string for the short help. + The string for the short help. @remarks An application might use short help for identifying the tool - purpose in a tooltip. + purpose in a tooltip. - @sa GetToolShortHelp(), SetToolLongHelp() + @see GetToolShortHelp(), SetToolLongHelp() */ void SetToolShortHelp(int toolId, const wxString& helpString); @@ -648,10 +615,9 @@ public: Toggles a tool on or off. This does not cause any event to get emitted. @param toolId - Tool in question. - + Tool in question. @param toggle - If @true, toggles the tool on, otherwise toggles it off. + If @true, toggles the tool on, otherwise toggles it off. @remarks Only applies to a tool that has been specified as a toggle tool. */ diff --git a/interface/tooltip.h b/interface/tooltip.h index 6abb42f458..20635ad568 100644 --- a/interface/tooltip.h +++ b/interface/tooltip.h @@ -32,7 +32,6 @@ public: /** Enable or disable tooltips globally. - May not be supported on all platforms (eg. wxCocoa). */ static void Enable(bool flag); @@ -56,7 +55,6 @@ public: /** Set the delay after which the tooltip appears. - May not be supported on all platforms (eg. wxCocoa). */ static void SetDelay(long msecs); diff --git a/interface/toplevel.h b/interface/toplevel.h index 318edbf9ba..c503ab4dec 100644 --- a/interface/toplevel.h +++ b/interface/toplevel.h @@ -27,7 +27,7 @@ public: /** Returns @true if the platform supports making the window translucent. - @sa SetTransparent() + @see SetTransparent() */ virtual bool CanSetTransparent(); @@ -40,10 +40,10 @@ public: Centres the window on screen. @param direction - Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL - or wxBOTH. + Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL + or wxBOTH. - @sa wxWindow::CentreOnParent + @see wxWindow::CentreOnParent */ void CentreOnScreen(int direction = wxBOTH); @@ -56,20 +56,20 @@ public: X11 (including GTK+) where the window manager may not support this operation and there is no way to find out. */ - bool EnableCloseButton(bool enable = @true); + bool EnableCloseButton(bool enable = true); /** Returns a pointer to the button which is the default for this window, or @c @NULL. The default button is the one activated by pressing the Enter key. */ - wxWindow * GetDefaultItem(); + wxWindow* GetDefaultItem(); /** Returns the standard icon of the window. The icon will be invalid if it hadn't been previously set by SetIcon(). - @sa GetIcons() + @see GetIcons() */ const wxIcon GetIcon(); @@ -77,18 +77,17 @@ public: Returns all icons associated with the window, there will be none of them if neither SetIcon() nor SetIcons() had been called before. - Use GetIcon() to get the main icon of the window. - @sa wxIconBundle + @see wxIconBundle */ const wxIconBundle GetIcons(); /** Gets a string containing the window title. - @sa SetTitle() + @see SetTitle() */ wxString GetTitle(); @@ -105,9 +104,9 @@ public: Iconizes or restores the window. @param iconize - If @true, iconizes the window; if @false, shows and restores it. + If @true, iconizes the window; if @false, shows and restores it. - @sa IsIconized(), Maximize(). + @see IsIconized(), Maximize(). */ void Iconize(bool iconize); @@ -128,7 +127,7 @@ public: /** Returns @true if the window is in fullscreen mode. - @sa ShowFullScreen() + @see ShowFullScreen() */ bool IsFullScreen(); @@ -144,12 +143,11 @@ public: /** @b @c This method is specific to wxUniversal port - Returns @true if this window is using native decorations, @false if we draw them ourselves. - @sa UseNativeDecorations(), - UseNativeDecorationsByDefault() + @see UseNativeDecorations(), + UseNativeDecorationsByDefault() */ bool IsUsingNativeDecorations(); @@ -157,32 +155,29 @@ public: Maximizes or restores the window. @param maximize - If @true, maximizes the window, otherwise it restores it. + If @true, maximizes the window, otherwise it restores it. - @sa Iconize() + @see Iconize() */ void Maximize(bool maximize); /** Use a system-dependent way to attract users attention to the window when it is in background. - - @e flags may have the value of either @c wxUSER_ATTENTION_INFO + @a flags may have the value of either @c wxUSER_ATTENTION_INFO (default) or @c wxUSER_ATTENTION_ERROR which results in a more drastic action. When in doubt, use the default value. - Note that this function should normally be only used when the application is not already in foreground. - This function is currently implemented for Win32 where it flashes the window icon in the taskbar, and for wxGTK with task bars supporting it. */ void RequestUserAttention(int flags = wxUSER_ATTENTION_INFO); /** - Changes the default item for the panel, usually @e win is a button. + Changes the default item for the panel, usually @a win is a button. - @sa GetDefaultItem() + @see GetDefaultItem() */ void SetDefaultItem(wxWindow win); @@ -190,11 +185,11 @@ public: Sets the icon for this window. @param icon - The icon to associate with this window. + The icon to associate with this window. @remarks The window takes a 'copy' of icon, but since it uses reference - counting, the copy is very quick. It is safe to - delete icon after calling this function. + counting, the copy is very quick. It is safe to delete + icon after calling this function. */ void SetIcon(const wxIcon& icon); @@ -205,9 +200,9 @@ public: only icon set by SetIcon(). @param icons - The icons to associate with this window. + The icons to associate with this window. - @sa wxIconBundle. + @see wxIconBundle. */ void SetIcons(const wxIconBundle& icons); @@ -217,19 +212,17 @@ public: Unavailable on full keyboard machines. @param id - Identifier for this button. - + Identifier for this button. @param label - Text to be displayed on the screen area dedicated to this hardware button. - + Text to be displayed on the screen area dedicated to this hardware button. @param subMenu - The menu to be opened after pressing this hardware button. + The menu to be opened after pressing this hardware button. - @sa SetRightMenu(). + @see SetRightMenu(). */ void SetLeftMenu(int id = wxID_ANY, const wxString& label = wxEmptyString, - wxMenu * subMenu = @NULL); + wxMenu* subMenu = NULL); /** A simpler interface for setting the size hints than @@ -249,19 +242,17 @@ public: Unavailable on full keyboard machines. @param id - Identifier for this button. - + Identifier for this button. @param label - Text to be displayed on the screen area dedicated to this hardware button. - + Text to be displayed on the screen area dedicated to this hardware button. @param subMenu - The menu to be opened after pressing this hardware button. + The menu to be opened after pressing this hardware button. - @sa SetLeftMenu(). + @see SetLeftMenu(). */ void SetRightMenu(int id = wxID_ANY, const wxString& label = wxEmptyString, - wxMenu * subMenu = @NULL); + wxMenu* subMenu = NULL); /** If the platform supports it, sets the shape of the window to that @@ -280,36 +271,34 @@ public: If a pair of values is not set (or set to -1), no constraints will be used. @param incW - Specifies the increment for sizing the width (GTK/Motif/Xt only). - + Specifies the increment for sizing the width (GTK/Motif/Xt only). @param incH - Specifies the increment for sizing the height (GTK/Motif/Xt only). - + Specifies the increment for sizing the height (GTK/Motif/Xt only). @param incSize - Increment size (only taken into account under X11-based - ports such as wxGTK/wxMotif/wxX11). + Increment size (only taken into account under X11-based + ports such as wxGTK/wxMotif/wxX11). @remarks Notice that this function not only prevents the user from - resizing the window outside the given bounds but it - also prevents the program itself from doing it using - SetSize. - */ - virtual void SetSizeHints(int minW, int minH, int maxW=-1, - int maxH=-1, - int incW=-1, - int incH=-1); + resizing the window outside the given bounds but it + also prevents the program itself from doing it using + SetSize. + */ + virtual void SetSizeHints(int minW, int minH, int maxW = -1, + int maxH = -1, + int incW = -1, + int incH = -1); void SetSizeHints(const wxSize& minSize, - const wxSize& maxSize=wxDefaultSize, - const wxSize& incSize=wxDefaultSize); + const wxSize& maxSize = wxDefaultSize, + const wxSize& incSize = wxDefaultSize); //@} /** Sets the window title. @param title - The window title. + The window title. - @sa GetTitle() + @see GetTitle() */ virtual void SetTitle(const wxString& title); @@ -317,10 +306,10 @@ public: If the platform supports it will set the window to be translucent @param alpha - Determines how opaque or transparent the window will - be, if the platform supports the opreration. A value of 0 sets the - window to be fully transparent, and a value of 255 sets the window - to be fully opaque. + Determines how opaque or transparent the window will + be, if the platform supports the opreration. A value of 0 sets the + window to be fully transparent, and a value of 255 sets the window + to be fully opaque. */ virtual bool SetTransparent(int alpha); @@ -334,52 +323,46 @@ public: virtual bool ShouldPreventAppExit(); /** - Depending on the value of @e show parameter the window is either shown full - screen or restored to its normal state. @e style is a bit list containing + Depending on the value of @a show parameter the window is either shown full + screen or restored to its normal state. @a style is a bit list containing some or all of the following values, which indicate what elements of the window to hide in full-screen mode: - wxFULLSCREEN_NOMENUBAR wxFULLSCREEN_NOTOOLBAR wxFULLSCREEN_NOSTATUSBAR wxFULLSCREEN_NOBORDER wxFULLSCREEN_NOCAPTION wxFULLSCREEN_ALL (all of the above) - This function has not been tested with MDI frames. - Note that showing a window full screen also actually @ref wxWindow::show Show()s if it hadn't been shown yet. - @sa IsFullScreen() + @see IsFullScreen() */ bool ShowFullScreen(bool show, long style = wxFULLSCREEN_ALL); /** @b @c This method is specific to wxUniversal port - Use native or custom-drawn decorations for this window only. Notice that to have any effect this method must be called before really creating the window, i.e. two step creation must be used: - @sa UseNativeDecorationsByDefault(), - IsUsingNativeDecorations() + @see UseNativeDecorationsByDefault(), + IsUsingNativeDecorations() */ - void UseNativeDecorations(bool native = @true); + void UseNativeDecorations(bool native = true); /** @b @c This method is specific to wxUniversal port - Top level windows in wxUniversal port can use either system-provided window decorations (i.e. title bar and various icons, buttons and menus in it) or draw the decorations themselves. By default the system decorations are used if they - are available, but this method can be called with @e native set to @false to + are available, but this method can be called with @a native set to @false to change this for all windows created after this point. - Also note that if @c WXDECOR environment variable is set, then custom decorations are used by default and so it may make sense to call this method with default argument if the application can't use custom decorations at all for some reason. */ - void UseNativeDecorationsByDefault(bool native = @true); + void UseNativeDecorationsByDefault(bool native = true); }; diff --git a/interface/treebase.h b/interface/treebase.h index 5b03d60811..1daf8cc422 100644 --- a/interface/treebase.h +++ b/interface/treebase.h @@ -32,7 +32,7 @@ public: /** Returns @true if this instance is referencing a valid tree item. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); //@{ /** diff --git a/interface/treebook.h b/interface/treebook.h index c79325f1fd..d4d469e12e 100644 --- a/interface/treebook.h +++ b/interface/treebook.h @@ -31,9 +31,9 @@ class wxTreebookEvent : public wxNotifyEvent { public: /** - @sa wxNotebookEvent + @see wxNotebookEvent */ - wxTreebookEvent(wxEventType commandType = wxEVT_@NULL, int id = 0, + wxTreebookEvent(wxEventType commandType = wxEVT_NULL, int id = 0, int nSel = wxNOT_FOUND, int nOldSel = wxNOT_FOUND); @@ -85,22 +85,17 @@ public: Creates an empty TreeBook control. @param parent - The parent window. Must be non-@NULL. - + The parent window. Must be non-@NULL. @param id - The window identifier. - + The window identifier. @param pos - The window position. - + The window position. @param size - The window size. - + The window size. @param style - The window style. See wxNotebook. - + The window style. See wxNotebook. @param name - The name of the control (used only under Motif). + The name of the control (used only under Motif). */ wxTreebook(); wxTreebook(wxWindow* parent, wxWindowID id, @@ -112,7 +107,6 @@ public: /** Destroys the wxTreebook object. - Also deletes all the pages owned by the control (inserted previously into it). */ ~wxTreebook(); @@ -122,7 +116,7 @@ public: @NULL could be specified for page to create an empty page. */ bool AddPage(wxWindow* page, const wxString& text, - bool bSelect = @false, + bool bSelect = false, int imageId = wxNOT_FOUND); /** @@ -130,19 +124,18 @@ public: @NULL could be specified for page to create an empty page. */ bool AddSubPage(wxWindow* page, const wxString& text, - bool bSelect = @false, + bool bSelect = false, int imageId = wxNOT_FOUND); /** Sets the image list for the page control and takes ownership of the list. - @sa wxImageList, SetImageList() + @see wxImageList, SetImageList() */ void AssignImageList(wxImageList* imageList); /** Changes the selection for the given page, returning the previous selection. - The call to this function does not generate the page changing events. This is the only difference with SetSelection(). See @ref overview_progevent "this topic" for more info. @@ -182,7 +175,7 @@ public: May generate page changing events (if selected page is under the collapsed branch, then its parent is autoselected). */ - bool ExpandNode(size_t pageId, bool expand = @true); + bool ExpandNode(size_t pageId, bool expand = true); /** Returns the image index for the given page. @@ -202,7 +195,6 @@ public: /** Returns the currently selected page, or wxNOT_FOUND if none was selected. - Note that this method may return either the previously or newly selected page when called from the EVT_TREEBOOK_PAGE_CHANGED handler depending on the platform and so wxTreebookEvent::GetSelection should be used @@ -217,17 +209,16 @@ public: */ bool InsertPage(size_t pagePos, wxWindow* page, const wxString& text, - bool bSelect = @false, + bool bSelect = false, int imageId = wxNOT_FOUND); /** Inserts a sub page under the specified page. - @NULL could be specified for page to create an empty page. */ bool InsertSubPage(size_t pagePos, wxWindow* page, const wxString& text, - bool bSelect = @false, + bool bSelect = false, int imageId = wxNOT_FOUND); /** @@ -239,7 +230,7 @@ public: Sets the image list for the page control. It does not take ownership of the image list, you must delete it yourself. - @sa wxImageList, AssignImageList() + @see wxImageList, AssignImageList() */ void SetImageList(wxImageList* imageList); @@ -256,13 +247,11 @@ public: /** Sets the selection for the given page, returning the previous selection. - The call to this function generates the page changing events. - This function is deprecated and should not be used in new code. Please use the ChangeSelection() function instead. - @sa GetSelection() + @see GetSelection() */ int SetSelection(size_t n); }; diff --git a/interface/treectrl.h b/interface/treectrl.h index a360e111d7..b67e630933 100644 --- a/interface/treectrl.h +++ b/interface/treectrl.h @@ -34,19 +34,16 @@ class wxTreeItemData : public wxClientData public: /** Default constructor. + In addition, the following methods are added in wxPython for accessing the object: - - @b GetData() - Returns a reference to the Python Object @b SetData(obj) - Associates a new Python Object with the wxTreeItemData */ @@ -138,28 +135,23 @@ public: Constructor, creating and showing a tree control. @param parent - Parent window. Must not be @NULL. - + Parent window. Must not be @NULL. @param id - Window identifier. The value wxID_ANY indicates a default value. - + Window identifier. The value wxID_ANY indicates a default value. @param pos - Window position. - + Window position. @param size - Window size. If wxDefaultSize is specified then the window is sized - appropriately. - + Window size. If wxDefaultSize is specified then the window is + sized + appropriately. @param style - Window style. See wxTreeCtrl. - + Window style. See wxTreeCtrl. @param validator - Window validator. - + Window validator. @param name - Window name. + Window name. - @sa Create(), wxValidator + @see Create(), wxValidator */ wxTreeCtrl(); wxTreeCtrl(wxWindow* parent, wxWindowID id, @@ -177,44 +169,39 @@ public: /** Adds the root node to the tree, returning the new item. - - The @e image and @e selImage parameters are an index within + The @a image and @a selImage parameters are an index within the normal image list specifying the image to use for unselected and selected items, respectively. - If @e image -1 and @e selImage is -1, the same image is used for + If @a image -1 and @a selImage is -1, the same image is used for both selected and unselected items. */ wxTreeItemId AddRoot(const wxString& text, int image = -1, int selImage = -1, - wxTreeItemData* data = @NULL); + wxTreeItemData* data = NULL); /** Appends an item to the end of the branch identified by @e parent, return a new item id. - - The @e image and @e selImage parameters are an index within + The @a image and @a selImage parameters are an index within the normal image list specifying the image to use for unselected and selected items, respectively. - If @e image -1 and @e selImage is -1, the same image is used for + If @a image -1 and @a selImage is -1, the same image is used for both selected and unselected items. */ wxTreeItemId AppendItem(const wxTreeItemId& parent, const wxString& text, int image = -1, int selImage = -1, - wxTreeItemData* data = @NULL); + wxTreeItemData* data = NULL); /** Sets the buttons image list. The button images assigned with this method will be automatically deleted by wxTreeCtrl as appropriate (i.e. it takes ownership of the list). - Setting or assigning the button image list enables the display of image buttons. Once enabled, the only way to disable the display of button images is to set the button image list to @NULL. - This function is only available in the generic version. - See also SetButtonsImageList(). */ void AssignButtonsImageList(wxImageList* imageList); @@ -223,7 +210,6 @@ public: Sets the normal image list. Image list assigned with this method will be automatically deleted by wxTreeCtrl as appropriate (i.e. it takes ownership of the list). - See also SetImageList(). */ void AssignImageList(wxImageList* imageList); @@ -232,7 +218,6 @@ public: Sets the state image list. Image list assigned with this method will be automatically deleted by wxTreeCtrl as appropriate (i.e. it takes ownership of the list). - See also SetStateImageList(). */ void AssignStateImageList(wxImageList* imageList); @@ -245,14 +230,14 @@ public: /** Collapses the root item. - @sa ExpandAll() + @see ExpandAll() */ void CollapseAll(); /** Collapses this item and all of its children, recursively. - @sa ExpandAllChildren() + @see ExpandAllChildren() */ void CollapseAllChildren(const wxTreeItemId& item); @@ -274,7 +259,6 @@ public: /** Deletes the specified item. A @c EVT_TREE_DELETE_ITEM event will be generated. - This function may cause a subsequent call to GetNextChild to fail. */ void Delete(const wxTreeItemId& item); @@ -290,7 +274,6 @@ public: Deletes all children of the given item (but not the item itself). Note that this will @b not generate any events unlike Delete() method. - If you have called SetItemHasChildren(), you may need to call it again since @e DeleteChildren does not automatically clear the setting. @@ -301,21 +284,19 @@ public: Starts editing the label of the given item. This function generates a EVT_TREE_BEGIN_LABEL_EDIT event which can be vetoed so that no text control will appear for in-place editing. - If the user changed the label (i.e. s/he does not press ESC or leave the text control without changes, a EVT_TREE_END_LABEL_EDIT event will be sent which can be vetoed as well. - @sa EndEditLabel(), wxTreeEvent + @see EndEditLabel(), wxTreeEvent */ void EditLabel(const wxTreeItemId& item); /** - Ends label editing. If @e cancelEdit is @true, the edit will be cancelled. - + Ends label editing. If @a cancelEdit is @true, the edit will be cancelled. This function is currently supported under Windows only. - @sa EditLabel() + @see EditLabel() */ void EndEditLabel(bool cancelEdit); @@ -340,37 +321,34 @@ public: void ExpandAllChildren(const wxTreeItemId& item); /** - Retrieves the rectangle bounding the @e item. If @e textOnly is @true, + Retrieves the rectangle bounding the @e item. If @a textOnly is @true, only the rectangle around the item's label will be returned, otherwise the item's image is also taken into account. - The return value is @true if the rectangle was successfully retrieved or @c @false - if it was not (in this case @e rect is not changed) -- for example, if the + if it was not (in this case @a rect is not changed) -- for example, if the item is currently invisible. - Notice that the rectangle coordinates are logical, not physical ones. So, for example, the x coordinate may be negative if the tree has a horizontal scrollbar and its position is not 0. */ bool GetBoundingRect(const wxTreeItemId& item, wxRect& rect, - bool textOnly = @false); + bool textOnly = false); /** Returns the buttons image list (from which application-defined button images are taken). - This function is only available in the generic version. */ wxImageList* GetButtonsImageList(); /** - Returns the number of items in the branch. If @e recursively is @true, + Returns the number of items in the branch. If @a recursively is @true, returns the total number of descendants, otherwise only one level of children is counted. */ unsigned int GetChildrenCount(const wxTreeItemId& item, - bool recursively = @true); + bool recursively = true); /** Returns the number of items in the control. @@ -380,27 +358,24 @@ 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. */ - wxTextCtrl * GetEditControl(); + wxTextCtrl* GetEditControl(); /** Returns the first child; call GetNextChild() for the next child. - For this enumeration function you must pass in a 'cookie' parameter which is opaque for the application but is necessary for the library to make these functions reentrant (i.e. allow more than one enumeration on one and the same object simultaneously). The cookie passed to GetFirstChild and GetNextChild should be the same variable. - Returns an invalid tree item (i.e. IsOk() returns @false) if there are no further children. - @sa GetNextChild(), GetNextSibling() + @see GetNextChild(), GetNextSibling() */ wxTreeItemId GetFirstChild(const wxTreeItemId& item, - wxTreeItemIdValue & cookie); + wxTreeItemIdValue& cookie); /** Returns the first visible item. @@ -454,8 +429,7 @@ wxPython provides the following shortcut method: //@} /** - Gets the specified item image. The value of @e which may be: - + Gets the specified item image. The value of @a which may be: wxTreeItemIcon_Normal to get the normal item image wxTreeItemIcon_Selected to get the selected item image (i.e. the image which is shown when the item is currently selected) @@ -493,60 +467,54 @@ wxPython provides the following shortcut method: Returns the last child of the item (or an invalid tree item if this item has no children). - @sa GetFirstChild(), GetNextSibling(), - GetLastChild() + @see GetFirstChild(), GetNextSibling(), + GetLastChild() */ wxTreeItemId GetLastChild(const wxTreeItemId& item); /** Returns the next child; call GetFirstChild() for the first child. - For this enumeration function you must pass in a 'cookie' parameter which is opaque for the application but is necessary for the library to make these functions reentrant (i.e. allow more than one enumeration on one and the same object simultaneously). The cookie passed to GetFirstChild and GetNextChild should be the same. - Returns an invalid tree item if there are no further children. - @sa GetFirstChild() + @see GetFirstChild() */ wxTreeItemId GetNextChild(const wxTreeItemId& item, - wxTreeItemIdValue & cookie); + wxTreeItemIdValue& cookie); /** Returns the next sibling of the specified item; call GetPrevSibling() for the previous sibling. - Returns an invalid tree item if there are no further siblings. - @sa GetPrevSibling() + @see GetPrevSibling() */ wxTreeItemId GetNextSibling(const wxTreeItemId& item); /** Returns the next visible item or an invalid item if this item is the last visible one. - - Notice that the @e item itself must be visible. + Notice that the @a item itself must be visible. */ wxTreeItemId GetNextVisible(const wxTreeItemId& item); /** Returns the previous sibling of the specified item; call GetNextSibling() for the next sibling. - Returns an invalid tree item if there are no further children. - @sa GetNextSibling() + @see GetNextSibling() */ wxTreeItemId GetPrevSibling(const wxTreeItemId& item); /** Returns the previous visible item or an invalid item if this item is the first visible one. - - Notice that the @e item itself must be visible. + Notice that the @a item itself must be visible. */ wxTreeItemId GetPrevVisible(const wxTreeItemId& item); @@ -554,7 +522,7 @@ wxPython provides the following shortcut method: Returns @true if the control will use a quick calculation for the best size, looking only at the first and last items. The default is @false. - @sa SetQuickBestSize() + @see SetQuickBestSize() */ bool GetQuickBestSize(); @@ -574,7 +542,6 @@ wxPython provides the following shortcut method: /** Fills the array of tree items passed in with the currently selected items. This function can be called only if the control has the wxTR_MULTIPLE style. - Returns the number of selected items. */ unsigned int GetSelections(wxArrayTreeItemIds& selection); @@ -587,63 +554,51 @@ wxPython provides the following shortcut method: /** Calculates which (if any) item is under the given point, returning the tree item - id at this point plus extra information @e flags. @e flags is a bitlist of the + id at this point plus extra information @e flags. @a flags is a bitlist of the following: - wxTREE_HITTEST_ABOVE - Above the client area. wxTREE_HITTEST_BELOW - Below the client area. wxTREE_HITTEST_NOWHERE - In the client area but below the last item. wxTREE_HITTEST_ONITEMBUTTON - On the button associated with an item. wxTREE_HITTEST_ONITEMICON - On the bitmap associated with an item. wxTREE_HITTEST_ONITEMINDENT - In the indentation associated with an item. wxTREE_HITTEST_ONITEMLABEL - On the label (string) associated with an item. wxTREE_HITTEST_ONITEMRIGHT - In the area to the right of an item. wxTREE_HITTEST_ONITEMSTATEICON - On the state icon for a tree view item that is in a user-defined state. wxTREE_HITTEST_TOLEFT - To the right of the client area. wxTREE_HITTEST_TORIGHT - To the left of the client area. */ wxTreeItemId HitTest(const wxPoint& point, int& flags); @@ -652,12 +607,11 @@ wxPython provides the following shortcut method: /** Inserts an item after a given one (@e previous) or before one identified by its position (@e before). - @e before must be less than the number of children. - - The @e image and @e selImage parameters are an index within + @a before must be less than the number of children. + The @a image and @a selImage parameters are an index within the normal image list specifying the image to use for unselected and selected items, respectively. - If @e image -1 and @e selImage is -1, the same image is used for + If @a image -1 and @a selImage is -1, the same image is used for both selected and unselected items. */ wxTreeItemId InsertItem(const wxTreeItemId& parent, @@ -665,18 +619,17 @@ wxPython provides the following shortcut method: const wxString& text, int image = -1, int selImage = -1, - wxTreeItemData* data = @NULL); + wxTreeItemData* data = NULL); wxTreeItemId InsertItem(const wxTreeItemId& parent, size_t before, const wxString& text, int image = -1, int selImage = -1, - wxTreeItemData* data = @NULL); + wxTreeItemData* data = NULL); //@} /** Returns @true if the given item is in bold state. - See also: SetItemBold() */ bool IsBold(const wxTreeItemId& item); @@ -711,14 +664,12 @@ wxPython provides the following shortcut method: items in the tree control. The function should return a negative, zero or positive value if the first item is less than, equal to or greater than the second one. - Please note that you @b must use wxRTTI macros DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS if you override this function because otherwise the base class considers that it is not overridden and uses the default comparison, i.e. sorts the items alphabetically, which allows it optimize away the calls to the virtual function completely. - See also: SortChildren() */ int OnCompareItems(const wxTreeItemId& item1, @@ -726,18 +677,17 @@ wxPython provides the following shortcut method: /** Appends an item as the first child of @e parent, return a new item id. - - The @e image and @e selImage parameters are an index within + The @a image and @a selImage parameters are an index within the normal image list specifying the image to use for unselected and selected items, respectively. - If @e image -1 and @e selImage is -1, the same image is used for + If @a image -1 and @a selImage is -1, the same image is used for both selected and unselected items. */ wxTreeItemId PrependItem(const wxTreeItemId& parent, const wxString& text, int image = -1, int selImage = -1, - wxTreeItemData* data = @NULL); + wxTreeItemData* data = NULL); /** Scrolls the specified item into view. @@ -746,22 +696,19 @@ wxPython provides the following shortcut method: /** Selects the given item. In multiple selection controls, can be also used to - deselect a currently selected item if the value of @e select is @false. + deselect a currently selected item if the value of @a select is @false. */ - void SelectItem(const wxTreeItemId& item, bool select = @true); + void SelectItem(const wxTreeItemId& item, bool select = true); /** Sets the buttons image list (from which application-defined button images are taken). The button images assigned with this method will @b not be deleted by wxTreeCtrl's destructor, you must delete it yourself. - Setting or assigning the button image list enables the display of image buttons. Once enabled, the only way to disable the display of button images is to set the button image list to @NULL. - This function is only available in the generic version. - See also AssignButtonsImageList(). */ void SetButtonsImageList(wxImageList* imageList); @@ -769,7 +716,6 @@ wxPython provides the following shortcut method: /** Sets the normal image list. Image list assigned with this method will @b not be deleted by wxTreeCtrl's destructor, you must delete it yourself. - See also AssignImageList(). */ void SetImageList(wxImageList* imageList); @@ -786,12 +732,11 @@ wxPython provides the following shortcut method: const wxColour& col); /** - Makes item appear in bold font if @e bold parameter is @true or resets it to + Makes item appear in bold font if @a bold parameter is @true or resets it to the normal state. - See also: IsBold() */ - void SetItemBold(const wxTreeItemId& item, bool bold = @true); + void SetItemBold(const wxTreeItemId& item, bool bold = true); //@{ /** @@ -817,7 +762,7 @@ wxPython note: void SetItemDropHighlight(const wxTreeItemId& item, - bool highlight = @true); + bool highlight = true); //@} /** @@ -825,7 +770,7 @@ wxPython note: text clipping, so the fonts height should be the same for all of them, although font attributes may vary. - @sa SetItemBold() + @see SetItemBold() */ void SetItemFont(const wxTreeItemId& item, const wxFont& font); @@ -836,11 +781,11 @@ wxPython note: usage and loading time. */ void SetItemHasChildren(const wxTreeItemId& item, - bool hasChildren = @true); + bool hasChildren = true); /** Sets the specified item image. See GetItemImage() - for the description of the @e which parameter. + for the description of the @a which parameter. */ void SetItemImage(const wxTreeItemId& item, int image, wxTreeItemIcon which = wxTreeItemIcon_Normal); @@ -868,7 +813,7 @@ wxPython note: looking only at the first and last items. Otherwise, it will look at all items. The default is @false. - @sa GetQuickBestSize() + @see GetQuickBestSize() */ void SetQuickBestSize(bool quickBestSize); @@ -877,7 +822,6 @@ wxPython note: taken). Image list assigned with this method will @b not be deleted by wxTreeCtrl's destructor, you must delete it yourself. - See also AssignStateImageList(). */ void SetStateImageList(wxImageList* imageList); @@ -895,7 +839,7 @@ wxPython note: should override that method to change the sort order (the default is ascending case-sensitive alphabetical order). - @sa wxTreeItemData, OnCompareItems() + @see wxTreeItemData, OnCompareItems() */ void SortChildren(const wxTreeItemId& item); @@ -946,10 +890,9 @@ class wxTreeEvent : public wxNotifyEvent public: /** ) - Constructor, used by wxWidgets itself only. */ - wxTreeEvent(wxEventType commandType, wxTreeCtrl * tree); + wxTreeEvent(wxEventType commandType, wxTreeCtrl* tree); /** Returns the item (valid for all events). diff --git a/interface/txtstrm.h b/interface/txtstrm.h index bcac40d883..4c4bdb43e3 100644 --- a/interface/txtstrm.h +++ b/interface/txtstrm.h @@ -58,21 +58,19 @@ class wxTextInputStream public: /** ) - Constructs a text stream associated to the given input stream. @param stream - The underlying input stream. - + The underlying input stream. @param sep - The initial string separator characters. - + The initial string separator characters. @param conv - In Unicode build only: The encoding converter used to convert the bytes in the - underlying input stream to characters. + In Unicode build only: The encoding converter used to convert the bytes in + the + underlying input stream to characters. */ wxTextInputStream(wxInputStream& stream, - const wxString& sep=" \t"); + const wxString& sep = " \t"); /** Destroys the wxTextInputStream object. @@ -86,40 +84,35 @@ public: /** Reads a unsigned 16 bit integer from the stream. - See wxTextInputStream::Read8 for the - description of the @e base parameter. + description of the @a base parameter. */ wxUint16 Read16(int base = 10); /** Reads a signed 16 bit integer from the stream. - See wxTextInputStream::Read8 for the - description of the @e base parameter. + description of the @a base parameter. */ wxInt16 Read16S(int base = 10); /** Reads a 32 bit unsigned integer from the stream. - See wxTextInputStream::Read8 for the - description of the @e base parameter. + description of the @a base parameter. */ wxUint32 Read32(int base = 10); /** Reads a 32 bit signed integer from the stream. - See wxTextInputStream::Read8 for the - description of the @e base parameter. + description of the @a base parameter. */ wxInt32 Read32S(int base = 10); /** Reads a single unsigned byte from the stream, given in base @e base. - - The value of @e base must be comprised between 2 and 36, inclusive, or + The value of @a base must be comprised between 2 and 36, inclusive, or be a special value 0 which means that the usual rules of @c C numbers are applied: if the number starts with @c 0x it is considered to be in base 16, if it starts with @c 0 - in base 8 and in base 10 otherwise. Note @@ -131,9 +124,8 @@ public: /** Reads a single signed byte from the stream. - See wxTextInputStream::Read8 for the - description of the @e base parameter. + description of the @a base parameter. */ wxInt8 Read8S(int base = 10); @@ -151,7 +143,6 @@ public: /** @b NB: This method is deprecated, use ReadLine() or ReadWord() instead. - Same as ReadLine(). */ wxString ReadString(); @@ -160,14 +151,13 @@ public: Reads a word (a sequence of characters until the next separator) from the input stream. - @sa SetStringSeparators() + @see SetStringSeparators() */ wxString ReadWord(); /** Sets the characters which are used to define the word boundaries in ReadWord(). - The default separators are the space and @c TAB characters. */ void SetStringSeparators(const wxString& sep); @@ -203,18 +193,16 @@ class wxTextOutputStream public: /** ) - Constructs a text stream object associated to the given output stream. @param stream - The output stream. - + The output stream. @param mode - The end-of-line mode. One of wxEOL_NATIVE, wxEOL_DOS, wxEOL_MAC and wxEOL_UNIX. - + The end-of-line mode. One of wxEOL_NATIVE, wxEOL_DOS, wxEOL_MAC and + wxEOL_UNIX. @param conv - In Unicode build only: The object used to convert - Unicode text into ASCII characters written to the output stream. + In Unicode build only: The object used to convert + Unicode text into ASCII characters written to the output stream. */ wxTextOutputStream(wxOutputStream& stream, wxEOL mode = wxEOL_NATIVE); @@ -242,27 +230,27 @@ public: void SetMode(wxEOL mode = wxEOL_NATIVE); /** - Writes the 16 bit integer @e i16 to the stream. + Writes the 16 bit integer @a i16 to the stream. */ void Write16(wxUint16 i16); /** - Writes the 32 bit integer @e i32 to the stream. + Writes the 32 bit integer @a i32 to the stream. */ void Write32(wxUint32 i32); /** - Writes the single byte @e i8 to the stream. + Writes the single byte @a i8 to the stream. */ void Write8(wxUint8 i8); /** - Writes the double @e f to the stream using the IEEE format. + Writes the double @a f to the stream using the IEEE format. */ virtual void WriteDouble(double f); /** - Writes @e string as a line. Depending on the end-of-line mode the end of + Writes @a string as a line. Depending on the end-of-line mode the end of line ('\n') characters in the string are converted to the correct line ending terminator. */ diff --git a/interface/uri.h b/interface/uri.h index eb502fe316..20b9d96b56 100644 --- a/interface/uri.h +++ b/interface/uri.h @@ -41,7 +41,7 @@ public: Copies this URI from another URI. @param uri - URI (Uniform Resource Identifier) to initialize with + URI (Uniform Resource Identifier) to initialize with */ wxURI(); wxURI(const wxChar* uri); @@ -50,7 +50,6 @@ public: /** Builds the URI from its individual components and adds proper separators. - If the URI is not a reference or is not resolved, the URI that is returned from Get is the same one passed to Create. @@ -60,7 +59,6 @@ public: /** Builds the URI from its individual components, adds proper separators, and returns escape sequences to normal characters. - Note that it is preferred to call this over Unescape(BuildURI()) since BuildUnescapedURI() performs some optimizations over the plain method. */ @@ -75,7 +73,7 @@ public: is no such thing as an "invalid" wxURI). uri - string to initialize from + string to initialize from */ const wxChar* Create(const wxString uri); @@ -88,11 +86,9 @@ public: /** Obtains the fragment of this URI. - The fragment of a URI is the last value of the URI, and is the value after a '' character after the path of the URI. - @c http://mysite.com/mypath#fragment */ const wxString GetFragment(); @@ -101,25 +97,20 @@ public: Obtains the host type of this URI, which is of type HostType(): - @b wxURI_REGNAME - Server is a host name, or the Server component itself is undefined. @b wxURI_IPV4ADDRESS - Server is a IP version 4 address (XXX.XXX.XXX.XXX) @b wxURI_IPV6ADDRESS - Server is a IP version 6 address ((XXX:)XXX::(XXX)XXX:XXX @b wxURI_IPVFUTURE - Server is an IP address, but not versions 4 or 6 */ const HostType GetHostType(); @@ -128,34 +119,27 @@ public: Returns the password part of the userinfo component of this URI. Note that this is explicitly depreciated by RFC 1396 and should generally be avoided if possible. - @c http://user:password@mysite.com/mypath */ const wxString GetPassword(); /** Returns the (normalized) path of the URI. - The path component of a URI comes directly after the scheme component if followed by zero or one slashes ('/'), or after the server/port component. - Absolute paths include the leading '/' character. - @c http://mysite.compath */ const wxString GetPath(); /** Returns a string representation of the URI's port. - The Port of a URI is a value after the server, and must come after a colon (:). - @c http://mysite.com:port - Note that you can easily get the numeric value of the port by using wxAtoi or wxString::Format. */ @@ -163,33 +147,27 @@ public: /** Returns the Query component of the URI. - The query component is what is commonly passed to a cgi application, and must come after the path component, and after a '?' character. - @c http://mysite.com/mypath?query */ const wxString GetQuery(); /** Returns the Scheme component of the URI. - The first part of the uri. - @c scheme://mysite.com */ const wxString GetScheme(); /** Returns the Server component of the URI. - The server of the uri can be a server name or a type of ip address. See GetHostType() for the possible values for the host type of the server component. - @c http://server/mypath */ const wxString GetServer(); @@ -198,17 +176,14 @@ public: Returns the username part of the userinfo component of this URI. Note that this is explicitly depreciated by RFC 1396 and should generally be avoided if possible. - @c http://user:password@mysite.com/mypath */ const wxString GetUser(); /** Returns the UserInfo component of the URI. - The component of a URI before the server component that is postfixed by a '@' character. - @c http://userinfo@mysite.com/mypath */ const wxString GetUserInfo(); @@ -258,7 +233,6 @@ public: /** To obtain individual components you can use one of the following methods - GetScheme() GetUserInfo() @@ -272,15 +246,12 @@ public: GetQuery() GetFragment() - However, you should check HasXXX before calling a get method, which determines whether or not the component referred to by the method is defined according to RFC 2396. - Consider an undefined component equivalent to a @NULL C string. - HasScheme() HasUserInfo() @@ -294,7 +265,6 @@ public: HasQuery() HasFragment() - Example: */ @@ -304,7 +274,6 @@ public: exist in this URI are copied from the base, and if this URI's path is not an absolute path (prefixed by a '/'), then this URI's path is merged with the base's path. - For instance, resolving "../mydir" from "http://mysite.com/john/doe" results in the scheme (http) and server (mysite.com) being copied into this URI, since they do not exist. In addition, since the path @@ -313,25 +282,23 @@ public: "http://mysite.com/john/mydir". @param base - Base URI to inherit from. Must be a full URI and not a reference - + Base URI to inherit from. Must be a full URI and not a reference @param flags - Currently either wxURI_STRICT or 0, in non-strict - mode some compatibility layers are enabled to allow loopholes from RFCs prior - to 2396 + Currently either wxURI_STRICT or 0, in non-strict + mode some compatibility layers are enabled to allow loopholes from RFCs + prior + to 2396 */ void Resolve(const wxURI& base, int flags = wxURI_STRICT); /** Translates all escape sequences (normal characters and returns the result. - This is the preferred over deprecated wxURL::ConvertFromURI. - If you want to unescape an entire wxURI, use BuildUnescapedURI() instead, as it performs some optimizations over this method. @param uri - string with escaped characters to convert + string with escaped characters to convert */ wxString Unescape(const wxString& uri); @@ -342,7 +309,7 @@ public: @param uricomp, otherwise it returns @false. uricomp - URI to compare to + URI to compare to */ void operator ==(const wxURI& uricomp); }; diff --git a/interface/url.h b/interface/url.h index 070c044e0c..dceb2096d1 100644 --- a/interface/url.h +++ b/interface/url.h @@ -32,59 +32,50 @@ public: to RFC 1738. In particular, file URLs must be of the format @c file://hostname/path/to/file otherwise GetError() will return a value different from @c wxURL_NOERR. - It is valid to leave out the hostname but slashes must remain in place - i.e. a file URL without a hostname must contain three consecutive slashes (e.g. @c file:///somepath/myfile). @param url - Url string to parse. + Url string to parse. */ -#define wxURL(const wxString& url = wxEmptyString) /* implementation is private */ + wxURL(const wxString& url = wxEmptyString); /** Destroys the URL object. */ -#define ~wxURL() /* implementation is private */ + ~wxURL(); /** Returns the last error. This error refers to the URL parsing or to the protocol. It can be one of these errors: - @b wxURL_NOERR - No error. @b wxURL_SNTXERR - Syntax error in the URL string. @b wxURL_NOPROTO - Found no protocol which can get this URL. @b wxURL_NOHOST - A host name is required for this protocol. @b wxURL_NOPATH - A path is required for this protocol. @b wxURL_CONNERR - Connection error. @b wxURL_PROTOERR - An error occurred during negotiation. */ wxURLError GetError(); @@ -93,18 +84,16 @@ public: Creates a new input stream on the specified URL. You can use all but seek functionality of wxStream. Seek isn't available on all streams. For example, HTTP or FTP streams don't deal with it. - Note that this method is somewhat deprecated, all future wxWidgets applications should really use wxFileSystem instead. - Example: @returns Returns the initialized stream. You will have to delete it - yourself. + yourself. - @sa wxInputStream + @see wxInputStream */ - wxInputStream * GetInputStream(); + wxInputStream* GetInputStream(); /** Returns a reference to the protocol which will be used to get the URL. @@ -115,23 +104,23 @@ public: Returns @true if this object is correctly initialized, i.e. if GetError() returns @c wxURL_NOERR. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); /** Sets the default proxy server to use to get the URL. The string specifies the proxy like this: hostname:port number. @param url_proxy - Specifies the proxy to use + Specifies the proxy to use - @sa SetProxy() + @see SetProxy() */ static void SetDefaultProxy(const wxString& url_proxy); /** Sets the proxy to use for this URL. - @sa SetDefaultProxy() + @see SetDefaultProxy() */ void SetProxy(const wxString& url_proxy); @@ -139,5 +128,5 @@ public: Initializes this object with the given URL and returns @c wxURL_NOERR if it's valid (see GetError() for more info). */ -#define wxURLError SetURL(const wxString& url) /* implementation is private */ + wxURLError SetURL(const wxString& url); }; diff --git a/interface/utils.h b/interface/utils.h index a80edb9d35..e8d79439f9 100644 --- a/interface/utils.h +++ b/interface/utils.h @@ -26,9 +26,9 @@ class wxWindowDisabler public: /** Disables all top level windows of the applications with the exception of - @e winToSkip if it is not @NULL. + @a winToSkip if it is not @NULL. */ - wxWindowDisabler(wxWindow * winToSkip = @NULL); + wxWindowDisabler(wxWindow* winToSkip = NULL); /** Reenables back the windows disabled by the constructor. @@ -95,26 +95,23 @@ wxPowerType wxGetPowerType(); This function returns the "user id" also known as "login name" under Unix i.e. something like "jsmith". It uniquely identifies the current user (on this system). - Under Windows or NT, this function first looks in the environment variables USER and LOGNAME; if neither of these is found, the entry @b UserId in the @b wxWidgets section of the WIN.INI file is tried. - The first variant of this function returns the login name if successful or an empty string otherwise. The second (deprecated) function returns @true if successful, @false otherwise. - @sa wxGetUserName + @see wxGetUserName */ wxString wxGetUserId(); -bool wxGetUserId(char * buf, int sz); +bool wxGetUserId(char* buf, int sz); //@} /** @b NB: This function is now obsolete, please use wxLogFatalError instead. - - Displays @e msg and exits. This writes to standard error under Unix, + Displays @a msg and exits. This writes to standard error under Unix, and pops up a message box under Windows. Used for fatal internal wxWidgets errors. See also wxError. */ @@ -133,24 +130,21 @@ wxBatteryState wxGetBatteryState(); /** @b NB: This function is obsolete, please use wxWindow::FindWindowByName instead. - Find a window by its name (as given in a window constructor or @b Create function call). - If @e parent is @NULL, the search will start from all top-level + If @a parent is @NULL, the search will start from all top-level frames and dialog boxes; if non-@NULL, the search will be limited to the given window hierarchy. The search is recursive in both cases. - If no such named window is found, @b wxFindWindowByLabel is called. */ -wxWindow * wxFindWindowByName(const wxString& name, - wxWindow * parent=@NULL); +wxWindow* wxFindWindowByName(const wxString& name, + wxWindow* parent = NULL); /** Changes the cursor back to the original cursor, for all windows in the application. Use with wxBeginBusyCursor. - See also wxIsBusy, wxBusyCursor. */ void wxEndBusyCursor(); @@ -160,6 +154,7 @@ void wxEndBusyCursor(); ids defined by the user code, use @c wxID_ANY to assign ids which are guaranteed to not conflict with the user-defined ids for the controls and menu items you create instead of using this function. + Generates an integer identifier unique to this run of the program. */ long wxNewId(); @@ -173,14 +168,11 @@ void wxRegisterId(long id); /** @b NB: This function is now obsolete, replaced by Log functions and wxLogDebug in particular. - Display a debugging message; under Windows, this will appear on the debugger command window, and under Unix, it will be written to standard error. - The syntax is identical to @b printf: pass a format string and a variable list of arguments. - @b Tip: under Windows, if your application crashes before the message appears in the debugging window, put a wxYield call after each wxDebugMsg call. wxDebugMsg seems to be broken under WIN32s @@ -191,11 +183,9 @@ void wxDebugMsg(const wxString& fmt, ... ); /** For normal keys, returns @true if the specified key is currently down. - For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns @true if the key is toggled such that its LED indicator is lit. There is currently no way to test whether togglable keys are up or down. - Even though there are virtual key codes defined for mouse buttons, they cannot be used with this function currently. */ @@ -206,14 +196,14 @@ bool wxGetKeyState(wxKeyCode key); user-readable form. For example, this function may return strings like @c Windows NT Version 4.0 or @c Linux 2.2.2 i386. - @sa ::wxGetOsVersion + @see ::wxGetOsVersion */ wxString wxGetOsDescription(); /** Return the (current) user's home directory. - @sa wxGetUserHome, wxStandardPaths + @see wxGetUserHome, wxStandardPaths */ wxString wxGetHomeDir(); @@ -238,33 +228,30 @@ void wxMicroSleep(unsigned long microseconds); underlying GUI toolkit. This is mainly used for diagnostic purposes and can be invoked by Ctrl-Alt-middle clicking on any wxWindow which doesn't otherwise handle this event. - This function is new since wxWidgets version 2.9.0 */ -void wxInfoMessageBox(wxWindow ( parent = @NULL); +void wxInfoMessageBox(wxWindow ( parent = NULL); /** Find a menu item identifier associated with the given frame's menu bar. */ - int wxFindMenuItemId(wxFrame * frame, const wxString& menuString, + int wxFindMenuItemId(wxFrame* frame, const wxString& menuString, const wxString& itemString); /** This function enables or disables all top level windows. It is used by ::wxSafeYield. */ - void wxEnableTopLevelWindows(bool enable = @true); + void wxEnableTopLevelWindows(bool enable = true); /** - Strips any menu codes from @e str and returns the result. - + Strips any menu codes from @a str and returns the result. By default, the functions strips both the mnemonics character (@c '') which is used to indicate a keyboard shortkey, and the accelerators, which are used only in the menu items and are separated from the main text by the - @c \t (TAB) character. By using @e flags of + @c \t (TAB) character. By using @a flags of @c wxStrip_Mnemonics or @c wxStrip_Accel to strip only the former or the latter part, respectively. - Notice that in most cases wxMenuItem::GetLabelFromText or wxControl::GetLabelText can be used instead. @@ -275,8 +262,7 @@ void wxInfoMessageBox(wxWindow ( parent = @NULL); /** @b NB: This function is now obsolete, please use wxLogError instead. - - Displays @e msg and continues. This writes to standard error under + Displays @a msg and continues. This writes to standard error under Unix, and pops up a message box under Windows. Used for internal wxWidgets errors. See also wxFatalError. */ @@ -284,15 +270,13 @@ void wxInfoMessageBox(wxWindow ( parent = @NULL); const wxString& title = "wxWidgets Internal Error"); /** - Open the @e url in user's default browser. If @e flags parameter contains + Open the @a url in user's default browser. If @a flags parameter contains @c wxBROWSER_NEW_WINDOW flag, a new window is opened for the URL - (currently this is only supported under Windows). The @e url may also be a + (currently this is only supported under Windows). The @a url may also be a local file path (with or without @c file:// prefix), if it doesn't correspond to an existing file and the URL has no scheme @c http:// is prepended to it by default. - Returns @true if the application was successfully launched. - Note that for some configurations of the running user, the application which is launched to open the given URL may be URL-dependent (e.g. a browser may be used for @@ -303,25 +287,24 @@ void wxInfoMessageBox(wxWindow ( parent = @NULL); /** Executes a command in an interactive shell window. If no command is specified, then just the shell is spawned. - See also wxExecute, @ref overview_sampleexec "Exec sample". */ - bool wxShell(const wxString& command = @NULL); + bool wxShell(const wxString& command = NULL); /** Gets the version and the operating system ID for currently running OS. See wxPlatformInfo for more details about wxOperatingSystemId. - @sa ::wxGetOsDescription, wxPlatformInfo + @see ::wxGetOsDescription, wxPlatformInfo */ - wxOperatingSystemId wxGetOsVersion(int * major = @NULL, - int * minor = @NULL); + wxOperatingSystemId wxGetOsVersion(int* major = NULL, + int* minor = NULL); /** Returns the FQDN (fully qualified domain host name) or an empty string on error. - @sa wxGetHostName + @see wxGetHostName */ wxString wxGetFullHostName(); @@ -330,45 +313,41 @@ void wxInfoMessageBox(wxWindow ( parent = @NULL); Use wxEndBusyCursor to revert the cursor back to its previous state. These two calls can be nested, and a counter ensures that only the outer calls take effect. - See also wxIsBusy, wxBusyCursor. */ - void wxBeginBusyCursor(wxCursor * cursor = wxHOURGLASS_CURSOR); + void wxBeginBusyCursor(wxCursor* cursor = wxHOURGLASS_CURSOR); /** Tells the system to delete the specified object when all other events have been processed. In some environments, it is necessary to use this instead of deleting a frame directly with the delete operator, because some GUIs will still send events to a deleted window. - Now obsolete: use wxWindow::Close instead. */ - void wxPostDelete(wxObject * object); + void wxPostDelete(wxObject* object); /** @b NB: This function is obsolete, please use wxWindow::FindWindowByLabel instead. - Find a window by its label. Depending on the type of window, the label may be a window title - or panel item label. If @e parent is @NULL, the search will start from all + or panel item label. If @a parent is @NULL, the search will start from all top-level frames and dialog boxes; if non-@NULL, the search will be limited to the given window hierarchy. The search is recursive in both cases. */ - wxWindow * wxFindWindowByLabel(const wxString& label, - wxWindow * parent=@NULL); + wxWindow* wxFindWindowByLabel(const wxString& label, + wxWindow* parent = NULL); /** This function is similar to wxYield, except that it disables the user input to all program windows before calling wxYield and re-enables it again - afterwards. If @e win is not @NULL, this window will remain enabled, + afterwards. If @a win is not @NULL, this window will remain enabled, allowing the implementation of some limited user interaction. - Returns the result of the call to ::wxYield. */ - bool wxSafeYield(wxWindow* win = @NULL, bool onlyIfNeeded = @false); + bool wxSafeYield(wxWindow* win = NULL, bool onlyIfNeeded = false); /** Returns the mouse position in screen coordinates. @@ -380,18 +359,17 @@ void wxInfoMessageBox(wxWindow ( parent = @NULL); the function creates a new character array and copies the data into it. A pointer to this data is returned. If unsuccessful, @NULL is returned. - The resource must be defined in the @c .rc file using the following syntax: + @code myResource TEXT file.ext @endcode where @c file.ext is a file that the resource compiler can find. - This function is available under Windows only. */ wxString wxLoadUserResource(const wxString& resourceName, - const wxString& resourceType="TEXT"); + const wxString& resourceType = "TEXT"); /** Returns the amount of free memory in bytes under environments which @@ -402,41 +380,37 @@ void wxInfoMessageBox(wxWindow ( parent = @NULL); /** This is a macro defined as @c getenv() or its wide char version in Unicode mode. - Note that under Win32 it may not return correct value for the variables set with wxSetEnv, use wxGetEnv function instead. */ - wxChar * wxGetEnv(const wxString& var); + wxChar* wxGetEnv(const wxString& var); //@{ /** Copies the current host machine's name into the supplied buffer. Please note that the returned name is @e not fully qualified, i.e. it does not include the domain name. - Under Windows or NT, this function first looks in the environment variable SYSTEM_NAME; if this is not found, the entry @b HostName in the @b wxWidgets section of the WIN.INI file is tried. - The first variant of this function returns the hostname if successful or an empty string otherwise. The second (deprecated) function returns @true if successful, @false otherwise. - @sa wxGetFullHostName + @see wxGetFullHostName */ wxString wxGetHostName(); - bool wxGetHostName(char * buf, int sz); + bool wxGetHostName(char* buf, int sz); //@} /** - Returns the current value of the environment variable @e var in @e value. - @e value may be @NULL if you just want to know if the variable exists + Returns the current value of the environment variable @a var in @e value. + @a value may be @NULL if you just want to know if the variable exists and are not interested in its value. - Returns @true if the variable exists, @false otherwise. */ - bool wxGetEnv(const wxString& var, wxString * value); + bool wxGetEnv(const wxString& var, wxString* value); /** Under X only, returns the current display name. See also wxSetDisplayName. @@ -445,17 +419,15 @@ void wxInfoMessageBox(wxWindow ( parent = @NULL); /** Ring the system bell. - Note that this function is categorized as a GUI one and so is not thread-safe. */ void wxBell(); /** - Returns the home directory for the given user. If the @e user is empty + Returns the home directory for the given user. If the @a user is empty (default value), this function behaves like wxGetHomeDir i.e. returns the current user home directory. - If the home directory couldn't be determined, an empty string is returned. */ wxString wxGetUserHome(const wxString& user = ""); @@ -466,21 +438,15 @@ void wxInfoMessageBox(wxWindow ( parent = @NULL); and it only takes the @c command argument, and returns a 3-element list @c ( status, output, errors ), where @c output and @c errors are array references. - Executes another program in Unix or Windows. - The first form takes a command string, such as @c "emacs file.txt". - The second form takes an array of values: a command, any number of arguments, terminated by @NULL. - The semantics of the third and fourth versions is different from the first two and is described in more details below. - - If @e flags parameter contains @c wxEXEC_ASYNC flag (the default), flow + If @a flags parameter contains @c wxEXEC_ASYNC flag (the default), flow of control immediately returns. If it contains @c wxEXEC_SYNC, the current application waits until the other program has terminated. - In the case of synchronous execution, the return value is the exit code of the process (which terminates by the moment the function returns) and will be -1 if the process couldn't be started and typically 0 if the process @@ -491,7 +457,6 @@ void wxInfoMessageBox(wxWindow ( parent = @NULL); while the child process is running. If you are sure that it is safe to not disable the program windows, you may pass @c wxEXEC_NODISABLE flag to prevent this automatic disabling from happening. - For asynchronous execution, however, the return value is the process id and zero value indicates that the command could not be executed. As an added complication, the return value of -1 in this case indicates that we didn't @@ -499,7 +464,6 @@ void wxInfoMessageBox(wxWindow ( parent = @NULL); case of using DDE under Windows for command execution). In particular, in this, and only this, case the calling code will not get the notification about process termination. - If callback isn't @NULL and if execution is asynchronous, wxProcess::OnTerminate will be called when the process finishes. Specifying this parameter also allows you to redirect the @@ -509,53 +473,46 @@ void wxInfoMessageBox(wxWindow ( parent = @NULL); flush an unnecessary console for the processes which don't create any windows anyhow) but a @c wxEXEC_NOHIDE flag can be used to prevent this from happening, i.e. with this flag the child process window will be shown normally. - Under Unix the flag @c wxEXEC_MAKE_GROUP_LEADER may be used to ensure that the new process is a group leader (this will create a new session if needed). Calling wxKill passing wxKILL_CHILDREN will kill this process as well as all of its children (except those which have started their own session). - The @c wxEXEC_NOEVENTS flag prevents processing of any events from taking place while the child process is running. It should be only used for very short-lived processes as otherwise the application windows risk becoming unresponsive from the users point of view. As this flag only makes sense with @c wxEXEC_SYNC, @c wxEXEC_BLOCK equal to the sum of both of these flags is provided as a convenience. - Finally, you may use the third overloaded version of this function to execute - a process (always synchronously, the contents of @e flags is or'd with + a process (always synchronously, the contents of @a flags is or'd with @c wxEXEC_SYNC) and capture its output in the array @e output. The fourth version adds the possibility to additionally capture the messages from - standard error output in the @e errors array. - + standard error output in the @a errors array. @b NB: Currently wxExecute() can only be used from the main thread, calling this function from another thread will result in an assert failure in debug build and won't work. @param command - The command to execute and any parameters to pass to it as a - single string. - + The command to execute and any parameters to pass to it as a + single string. @param argv - The command to execute should be the first element of this - array, any additional ones are the command parameters and the array must be - terminated with a @NULL pointer. - + The command to execute should be the first element of this + array, any additional ones are the command parameters and the array must be + terminated with a @NULL pointer. @param flags - Combination of bit masks wxEXEC_ASYNC, - wxEXEC_SYNC and wxEXEC_NOHIDE - + Combination of bit masks wxEXEC_ASYNC, + wxEXEC_SYNC and wxEXEC_NOHIDE @param callback - An optional pointer to wxProcess + An optional pointer to wxProcess - @sa wxShell, wxProcess, @ref overview_sampleexec "Exec sample". + @see wxShell, wxProcess, @ref overview_sampleexec "Exec sample". */ long wxExecute(const wxString& command, int sync = wxEXEC_ASYNC, - wxProcess * callback = @NULL); - wxPerl note: long wxExecute(char ** argv, + wxProcess* callback = NULL); + wxPerl note: long wxExecute(char** argv, int flags = wxEXEC_ASYNC, - wxProcess * callback = @NULL); + wxProcess* callback = NULL); wxPerl note: long wxExecute(const wxString& command, wxArrayString& output, int flags = 0); @@ -577,7 +534,6 @@ void wxInfoMessageBox(wxWindow ( parent = @NULL); since the program could be running in emulation mode or in a mixed 32/64 bit system (bi-architecture operating system). - Very important: this function is not 100% reliable on some systems given the fact that there isn't always a standard way to do a reliable check on the OS @@ -587,14 +543,14 @@ void wxInfoMessageBox(wxWindow ( parent = @NULL); /** Returns the number uniquely identifying the current process in the system. - If an error occurs, 0 is returned. */ unsigned long wxGetProcessId(); /** - Equivalent to the Unix kill function: send the given signal @e sig to the + Equivalent to the Unix kill function: send the given signal @a sig to the process with PID @e pid. The valid signal values are + @code enum wxSignal { @@ -620,9 +576,9 @@ void wxInfoMessageBox(wxWindow ( parent = @NULL); @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning under both Unix and Windows but all the other signals are equivalent to @c wxSIGTERM under Windows. - - Returns 0 on success, -1 on failure. If @e rc parameter is not @NULL, it will + Returns 0 on success, -1 on failure. If @a rc parameter is not @NULL, it will be filled with an element of @c wxKillError enum: + @code enum wxKillError { @@ -634,15 +590,15 @@ void wxInfoMessageBox(wxWindow ( parent = @NULL); }; @endcode - The @e flags parameter can be wxKILL_NOCHILDREN (the default), + The @a flags parameter can be wxKILL_NOCHILDREN (the default), or wxKILL_CHILDREN, in which case the child processes of this process will be killed too. Note that under Unix, for wxKILL_CHILDREN to work you should have created the process by passing wxEXEC_MAKE_GROUP_LEADER to wxExecute. - @sa wxProcess::Kill, wxProcess::Exists, @ref overview_sampleexec "Exec sample" + @see wxProcess::Kill, wxProcess::Exists, @ref overview_sampleexec "Exec sample" */ - int wxKill(long pid, int sig = wxSIGTERM, wxKillError rc = @NULL, + int wxKill(long pid, int sig = wxSIGTERM, wxKillError rc = NULL, int flags = 0); /** @@ -656,7 +612,6 @@ void wxInfoMessageBox(wxWindow ( parent = @NULL); /** Returns @true if between two wxBeginBusyCursor and wxEndBusyCursor calls. - See also wxBusyCursor. */ bool wxIsBusy(); @@ -666,11 +621,10 @@ void wxInfoMessageBox(wxWindow ( parent = @NULL); Copies the user's email address into the supplied buffer, by concatenating the values returned by wxGetFullHostName and wxGetUserId. - Returns @true if successful, @false otherwise. */ wxString wxGetEmailAddress(); - bool wxGetEmailAddress(char * buf, int sz); + bool wxGetEmailAddress(char* buf, int sz); //@} /** @@ -679,12 +633,11 @@ void wxInfoMessageBox(wxWindow ( parent = @NULL); void wxSleep(int secs); /** - Sets the value of the environment variable @e var (adding it if necessary) + Sets the value of the environment variable @a var (adding it if necessary) to @e value. - Returns @true on success. - @sa wxUnsetEnv + @see wxUnsetEnv */ bool wxSetEnv(const wxString& var, const wxString& value); @@ -693,7 +646,7 @@ void wxInfoMessageBox(wxWindow ( parent = @NULL); endian). The check is performed at run-time. - @sa @ref overview_byteordermacros "Byte order macros" + @see @ref overview_byteordermacros "Byte order macros" */ bool wxIsPlatformLittleEndian(); @@ -705,7 +658,6 @@ void wxInfoMessageBox(wxWindow ( parent = @NULL); windows from this point on. Setting the display within an application allows multiple displays to be used. - See also wxGetDisplayName. */ void wxSetDisplayName(const wxString& displayName); diff --git a/interface/valgen.h b/interface/valgen.h index c0a477067d..854507dcec 100644 --- a/interface/valgen.h +++ b/interface/valgen.h @@ -42,13 +42,12 @@ public: used for wxDatePickerCtrl. @param validator - Validator to copy. - + Validator to copy. @param valPtr - A pointer to a variable that contains the value. This variable - should have a lifetime equal to or longer than the validator lifetime (which is - usually - determined by the lifetime of the window). + A pointer to a variable that contains the value. This variable + should have a lifetime equal to or longer than the validator lifetime + (which is usually + determined by the lifetime of the window). */ wxGenericValidator(const wxGenericValidator& validator); wxGenericValidator(bool* valPtr); diff --git a/interface/validate.h b/interface/validate.h index 9ca2e96cbc..a0c4ec1ace 100644 --- a/interface/validate.h +++ b/interface/validate.h @@ -58,7 +58,6 @@ public: and brushes, it does not make sense to have a reference counting scheme to do this cloning, because all validators should have separate data. - This base function returns @NULL. */ virtual wxObject* Clone(); @@ -72,7 +71,7 @@ public: This functions switches on or turns off the error sound produced by the validators if an invalid key is pressed. */ - void SetBellOnError(bool doIt = @true); + void SetBellOnError(bool doIt = true); /** Associates a window with the validator. diff --git a/interface/valtext.h b/interface/valtext.h index 40849a7b95..7e9db73762 100644 --- a/interface/valtext.h +++ b/interface/valtext.h @@ -31,73 +31,127 @@ public: Constructor, taking a style and optional pointer to a wxString variable. @param style - A bitlist of flags, which can be: + A bitlist of flags, which can be: - wxFILTER_NONE - No filtering takes place. - wxFILTER_ASCII - Non-ASCII characters are filtered out. + wxFILTER_NONE - wxFILTER_ALPHA - Non-alpha characters are filtered out. - wxFILTER_ALPHANUMERIC + No filtering takes place. - Non-alphanumeric characters are filtered out. - wxFILTER_NUMERIC - Non-numeric characters are filtered out. + wxFILTER_ASCII - wxFILTER_INCLUDE_LIST - Use an include list. The validator - checks if the user input is on the list, complaining if not. See - SetIncludes(). - wxFILTER_EXCLUDE_LIST + Non-ASCII characters are filtered out. - Use an exclude list. The validator - checks if the user input is on the list, complaining if it is. See - SetExcludes(). - wxFILTER_INCLUDE_CHAR_LIST - Use an include list. The validator - checks if each input character is in the list (one character per list element), - complaining if not. - See SetIncludes(). + wxFILTER_ALPHA - wxFILTER_EXCLUDE_CHAR_LIST - Use an include list. The validator - checks if each input character is in the list (one character per list element), - complaining if it is. - See SetExcludes(). + Non-alpha characters are filtered out. + + + + + + wxFILTER_ALPHANUMERIC + + + + + Non-alphanumeric characters are filtered out. + + + + + + wxFILTER_NUMERIC + + + + + Non-numeric characters are filtered out. + + + + + + wxFILTER_INCLUDE_LIST + + + + + Use an include list. The validator + checks if the user input is on the list, complaining if not. See + SetIncludes(). + + + + + + wxFILTER_EXCLUDE_LIST + + + + + Use an exclude list. The validator + checks if the user input is on the list, complaining if it is. See + SetExcludes(). + + + + + + wxFILTER_INCLUDE_CHAR_LIST + + + + + Use an include list. The validator + checks if each input character is in the list (one character per list + element), complaining if not. + See SetIncludes(). + + + + + + wxFILTER_EXCLUDE_CHAR_LIST + + + + + Use an include list. The validator + checks if each input character is in the list (one character per list + element), complaining if it is. + See SetExcludes(). @param valPtr - A pointer to a wxString variable that contains the value. This variable - should have a lifetime equal to or longer than the validator lifetime (which is - usually - determined by the lifetime of the window). + A pointer to a wxString variable that contains the value. This variable + should have a lifetime equal to or longer than the validator lifetime + (which is usually + determined by the lifetime of the window). */ wxTextValidator(const wxTextValidator& validator); wxTextValidator(long style = wxFILTER_NONE, - wxString* valPtr = @NULL); + wxString* valPtr = NULL); //@} /** diff --git a/interface/variant.h b/interface/variant.h index 5034f9f055..2855455edc 100644 --- a/interface/variant.h +++ b/interface/variant.h @@ -132,7 +132,6 @@ public: /** Destructor. - Note that destructor is protected, so wxVariantData cannot usually be deleted. Instead, wxVariantData::DecRef should be called. See @ref overview_refcountdestruct "reference-counted object destruction" for @@ -158,7 +157,7 @@ public: //@{ /** - Retrieves and converts the value of this variant to the type that @e value is. + Retrieves and converts the value of this variant to the type that @a value is. */ bool Convert(long* value); bool Convert(bool* value); @@ -169,7 +168,7 @@ public: //@} /** - Deletes the zero-based @e item from the list. + Deletes the zero-based @a item from the list. */ bool Delete(size_t item); @@ -235,7 +234,6 @@ public: /** Returns the value type as a string. The built-in types are: bool, char, datetime, double, list, long, string, arrstring, void*. - If the variant is null, the value type returned is the string "null" (not the empty string). */ @@ -263,7 +261,7 @@ public: bool IsNull(); /** - Returns @true if @e type matches the type of the variant, @false otherwise. + Returns @true if @a type matches the type of the variant, @false otherwise. */ bool IsType(const wxString& type); @@ -284,7 +282,7 @@ public: wxString MakeString(); /** - Returns @true if @e value matches an element in the list. + Returns @true if @a value matches an element in the list. */ bool Member(const wxVariant& value); @@ -369,7 +367,7 @@ public: //@{ /** - Returns a reference to the value at @e idx (zero-based). This can be used + Returns a reference to the value at @a idx (zero-based). This can be used to change the value at this index. */ wxVariant operator [](size_t idx); @@ -453,7 +451,6 @@ public: /** Decreases reference count. If the count reaches zero, the object is automatically deleted. - Note that destructor of wxVariantData is protected, so delete cannot be used as normal. Instead, DecRef() should be called. */ @@ -462,7 +459,7 @@ public: /** Returns @true if this object is equal to @e data. */ -#define bool Eq(wxVariantData& data) /* implementation is private */ + bool Eq(wxVariantData& data); /** Returns the string type of the data. @@ -484,7 +481,7 @@ public: //@{ /** - Reads the data from @e stream or @e string. + Reads the data from @a stream or @e string. */ bool Read(ostream& stream); bool Read(wxString& string); @@ -492,7 +489,7 @@ public: //@{ /** - Writes the data to @e stream or @e string. + Writes the data to @a stream or @e string. */ bool Write(ostream& stream); bool Write(wxString& string); @@ -504,5 +501,5 @@ public: the data is of this type (the check is done during the run-time) or @NULL otherwise. */ - classname * wxGetVariantCast(); + classname* wxGetVariantCast(); }; diff --git a/interface/vector.h b/interface/vector.h index 26b4ede8e1..7b6e04158d 100644 --- a/interface/vector.h +++ b/interface/vector.h @@ -22,8 +22,7 @@ @category{FIXME} @seealso - @ref overview_wxcontaineroverview "Container classes overview", wxListT, - wxArrayT + @ref overview_wxcontaineroverview, wxListT, wxArrayT */ class wxVector { @@ -108,7 +107,6 @@ public: /** ) - Insert an item. When using values other than built-in integrals or classes with reference counting this can be an inefficient operation. @@ -139,7 +137,7 @@ public: void push_back(const value_type& v); /** - Reserves more memory of @e n is greater then + Reserves more memory of @a n is greater then wxVector::size. Other this call has no effect. */ diff --git a/interface/vlbox.h b/interface/vlbox.h index f03e2cb666..67e2e4fa71 100644 --- a/interface/vlbox.h +++ b/interface/vlbox.h @@ -61,10 +61,8 @@ public: Creates the control. To finish creating it you also should call SetItemCount() to let it know about the number of items it contains. - The only special style which may be used with wxVListBox is @c wxLB_MULTIPLE which indicates that the listbox should support multiple selection. - Returns @true on success or @false if the control couldn't be created */ bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, @@ -75,24 +73,20 @@ public: /** Deselects all the items in the listbox. - Returns @true if any items were changed, i.e. if there had been any selected items before, or @false if all the items were already deselected. - This method is only valid for multi selection listboxes. - @sa SelectAll(), Select() + @see SelectAll(), Select() */ bool DeselectAll(); /** Returns the index of the first selected item in the listbox or @c wxNOT_FOUND if no items are currently selected. - - @e cookie is an opaque parameter which should be passed to the subsequent + @a cookie is an opaque parameter which should be passed to the subsequent calls to GetNextSelected(). It is needed in order to allow parallel iterations over the selected items. - Here is a typical example of using these functions: This method is only valid for multi selection listboxes. @@ -102,7 +96,7 @@ public: /** Get the number of items in the control. - @sa SetItemCount() + @see SetItemCount() */ size_t GetItemCount(); @@ -110,28 +104,26 @@ public: Returns the margins used by the control. The @c x field of the returned point is the horizontal margin and the @c y field is the vertical one. - @sa SetMargins() + @see SetMargins() */ wxPoint GetMargins(); /** Returns the index of the next selected item or @c wxNOT_FOUND if there are no more. - This method is only valid for multi selection listboxes. - @sa GetFirstSelected() + @see GetFirstSelected() */ int GetNextSelected(unsigned long& cookie); /** Returns the number of the items currently selected. - It is valid for both single and multi selection controls. In the former case it may only return 0 or 1 however. - @sa IsSelected(), GetFirstSelected(), - GetNextSelected() + @see IsSelected(), GetFirstSelected(), + GetNextSelected() */ size_t GetSelectedCount(); @@ -144,7 +136,7 @@ public: Returns the background colour used for the selected cells. By default the standard system colour is used. - @sa wxSystemSettings::GetColour, SetSelectionBackground() + @see wxSystemSettings::GetColour, SetSelectionBackground() */ const wxColour GetSelectionBackground(); @@ -157,7 +149,6 @@ public: /** Returns @true if this item is the current one, @false otherwise. - Current item is always the same as selected one for the single selection listbox and in this case this method is equivalent to IsSelected() but they are different for multi @@ -174,7 +165,6 @@ public: /** This method is used to draw the items background and, maybe, a border around it. - The base class version implements a reasonable default behaviour which consists in drawing the selected item with the standard background colour and drawing a border around the item if it is either selected or @@ -187,14 +177,12 @@ public: with the given index on the provided DC. @param dc - The device context to use for drawing - + The device context to use for drawing @param rect - The bounding rectangle for the item being drawn (DC clipping - region is set to this rectangle before calling this function) - + The bounding rectangle for the item being drawn (DC clipping + region is set to this rectangle before calling this function) @param n - The index of the item to be drawn + The index of the item to be drawn */ void OnDrawItem(wxDC& dc, const wxRect& rect, size_t n); @@ -202,17 +190,14 @@ public: This method may be used to draw separators between the lines. The rectangle passed to it may be modified, typically to deflate it a bit before passing to OnDrawItem(). - The base class version of this method doesn't do anything. @param dc - The device context to use for drawing - + The device context to use for drawing @param rect - The bounding rectangle for the item - + The bounding rectangle for the item @param n - The index of the item + The index of the item */ void OnDrawSeparator(wxDC& dc, wxRect& rect, size_t n); @@ -225,42 +210,35 @@ public: /** Selects or deselects the specified item which must be valid (i.e. not equal to @c wxNOT_FOUND). - Return @true if the items selection status has changed or @false otherwise. - This function is only valid for the multiple selection listboxes, use SetSelection() for the single selection ones. */ - bool Select(size_t item, bool select = @true); + bool Select(size_t item, bool select = true); /** Selects all the items in the listbox. - Returns @true if any items were changed, i.e. if there had been any unselected items before, or @false if all the items were already selected. - This method is only valid for multi selection listboxes. - @sa DeselectAll(), Select() + @see DeselectAll(), Select() */ bool SelectAll(); /** Selects all items in the specified range which may be given in any order. - Return @true if the items selection status has changed or @false otherwise. - This method is only valid for multi selection listboxes. - @sa SelectAll(), Select() + @see SelectAll(), Select() */ bool SelectRange(size_t from, size_t to); /** Set the number of items to be shown in the control. - This is just a synonym for wxVScrolledWindow::SetRowCount. */ @@ -271,7 +249,6 @@ public: Set the margins: horizontal margin is the distance between the window border and the item contents while vertical margin is half of the distance between items. - By default both margins are 0. */ void SetMargins(const wxPoint& pt); @@ -282,7 +259,6 @@ public: Set the selection to the specified item, if it is -1 the selection is unset. The selected item will be automatically scrolled into view if it isn't currently visible. - This method may be used both with single and multiple selection listboxes. */ void SetSelection(int selection); @@ -291,19 +267,17 @@ public: Sets the colour to be used for the selected cells background. The background of the standard cells may be changed by simply calling wxWindow::SetBackgroundColour. - Notice that using non-default background colour may result in control having appearance different from the similar native controls and so should in general be avoided. - @sa GetSelectionBackground() + @see GetSelectionBackground() */ void SetSelectionBackground(const wxColour& col); /** Toggles the state of the specified @e item, i.e. selects it if it was unselected and deselects it if it was selected. - This method is only valid for multi selection listboxes. */ void Toggle(size_t item); diff --git a/interface/vscroll.h b/interface/vscroll.h index cf3cfaa103..aea2012930 100644 --- a/interface/vscroll.h +++ b/interface/vscroll.h @@ -41,7 +41,6 @@ public: to this function so derived classes can override either just the height or the width estimation, or just estimate both differently if desired in any wxHVScrolledWindow derived class. - Please note that this function will not be called if @c EstimateTotalSize() is overridden in your derived class. */ @@ -50,7 +49,7 @@ public: /** Returns the number of columns the target window contains. - @sa SetColumnCount() + @see SetColumnCount() */ size_t GetColumnCount(); @@ -82,13 +81,11 @@ public: calculating the columns' sizes is a relatively expensive operation as it gives your code a chance to calculate several of them at once and cache the result if necessary. - @c OnGetColumnsWidthHint() is normally called just before OnGetColumnWidth() but you shouldn't rely on the latter being called for all columns in the interval specified here. It is also possible that OnGetColumnWidth() will be called for units outside of this interval, so this is really just a hint, not a promise. - Finally, note that columnMin is inclusive, while columnMax is exclusive. */ virtual void OnGetColumnsWidthHint(size_t columnMin, @@ -116,7 +113,6 @@ public: Scroll by the specified number of columns which may be positive (to scroll right) or negative (to scroll left). - Returns @true if the window was scrolled, @false otherwise (for example, if we're trying to scroll right but we are already showing the last column). @@ -126,7 +122,6 @@ public: /** Scroll to the specified column. It will become the first visible column in the window. - Returns @true if we scrolled the window, @false if nothing was done. */ bool ScrollToColumn(size_t column); @@ -175,7 +170,6 @@ public: to this function so derived classes can override either just the height or the width estimation, or just estimate both differently if desired in any wxHVScrolledWindow derived class. - Please note that this function will not be called if @c EstimateTotalSize() is overridden in your derived class. */ @@ -184,7 +178,7 @@ public: /** Returns the number of rows the target window contains. - @sa SetRowCount() + @see SetRowCount() */ size_t GetRowCount(); @@ -216,13 +210,11 @@ public: calculating the rows' sizes is a relatively expensive operation as it gives your code a chance to calculate several of them at once and cache the result if necessary. - @c OnGetRowsHeightHint() is normally called just before OnGetRowHeight() but you shouldn't rely on the latter being called for all rows in the interval specified here. It is also possible that OnGetRowHeight() will be called for units outside of this interval, so this is really just a hint, not a promise. - Finally, note that rowMin is inclusive, while rowMax is exclusive. */ virtual void OnGetRowsHeightHint(size_t rowMin, size_t rowMax); @@ -247,7 +239,6 @@ public: /** Scroll by the specified number of rows which may be positive (to scroll down) or negative (to scroll up). - Returns @true if the window was scrolled, @false otherwise (for example, if we're trying to scroll down but we are already showing the last row). @@ -256,7 +247,6 @@ public: /** Scroll to the specified row. It will become the first visible row in the window. - Returns @true if we scrolled the window, @false if nothing was done. */ bool ScrollToRow(size_t row); @@ -315,7 +305,7 @@ public: for variable scroll unit sizes), a call to this function with a coordinate of 15 will return -85. - @sa CalcUnscrolledPosition() + @see CalcUnscrolledPosition() */ int CalcScrolledPosition(int coord); @@ -326,7 +316,7 @@ public: allows for variable scroll unit sizes), a call to this function with a coordinate of 15 will return 115. - @sa CalcScrolledPosition() + @see CalcScrolledPosition() */ int CalcUnscrolledPosition(int coord); @@ -338,7 +328,7 @@ public: responsible for repainting any invalidated areas of the window yourself to account for the new scroll position. */ - void EnablePhysicalScrolling(bool scrolling = @true); + void EnablePhysicalScrolling(bool scrolling = true); /** When the number of scroll units change, we try to estimate the total size of @@ -347,7 +337,6 @@ public: if the user code may estimate the average size better or faster than we do, it should override this function to implement its own logic. This function should return the best guess for the total virtual window size. - Note that although returning a totally wrong value would still work, it risks resulting in very strange scrollbar behaviour so this function should really try to make the best guess possible. @@ -359,7 +348,7 @@ public: window size with respect to the opposing orientation. If this is a vertical scrolled window, it should return the height. - @sa GetOrientationTargetSize() + @see GetOrientationTargetSize() */ virtual int GetNonOrientationTargetSize(); @@ -374,7 +363,7 @@ public: window size with respect to the orientation this helper is working with. If this is a vertical scrolled window, it should return the width. - @sa GetNonOrientationTargetSize() + @see GetNonOrientationTargetSize() */ virtual int GetOrientationTargetSize(); @@ -382,7 +371,7 @@ public: This function will return the target window this helper class is currently scrolling. - @sa SetTargetWindow() + @see SetTargetWindow() */ wxWindow* GetTargetWindow(); @@ -414,13 +403,11 @@ public: calculating the units' sizes is a relatively expensive operation as it gives your code a chance to calculate several of them at once and cache the result if necessary. - @c OnGetUnitsSizeHint() is normally called just before OnGetUnitSize() but you shouldn't rely on the latter being called for all units in the interval specified here. It is also possible that OnGetUnitSize() will be called for units outside of this interval, so this is really just a hint, not a promise. - Finally, note that unitMin is inclusive, while unitMax is exclusive. */ virtual void OnGetUnitsSizeHint(size_t unitMin, size_t unitMax); @@ -436,7 +423,7 @@ public: scroll only a portion the area between the scrollbars like a spreadsheet where only the cell area will move). - @sa GetTargetWindow() + @see GetTargetWindow() */ void SetTargetWindow(wxWindow* target); @@ -495,28 +482,22 @@ public: /** This is the normal constructor, no need to call @c Create() after using this one. - Note that @c wxVSCROLL is always automatically added to our style, there is no need to specify it explicitly. @param parent - The parent window, must not be @NULL - + The parent window, must not be @NULL @param id - The identifier of this window, wxID_ANY by default - + The identifier of this window, wxID_ANY by default @param pos - The initial window position - + The initial window position @param size - The initial window size - + The initial window size @param style - The window style. There are no special style bits defined for - this class. - + The window style. There are no special style bits defined for + this class. @param name - The name for this window; usually not used + The name for this window; usually not used */ wxVScrolledWindow(); wxVScrolledWindow(wxWindow* parent, wxWindowID id = wxID_ANY, @@ -530,7 +511,6 @@ public: Same as the @ref wxvscrolledwindow() "non-default constuctor" but returns status code: @true if ok, @false if the window couldn't be created. - Just as with the constructor above, the @c wxVSCROLL style is always used, there is no need to specify it explicitly. */ @@ -551,7 +531,6 @@ public: as "rows" and "columns", respectively. This is to help clear some confusion in not only those classes, but also in wxHVScrolledWindow where functions are inherited from both. - You are encouraged to update any existing code using these function to use the new replacements mentioned below, and avoid using these functions for any new code as they are deprecated. @@ -616,28 +595,22 @@ public: /** This is the normal constructor, no need to call @c Create() after using this one. - Note that @c wxHSCROLL and @c wxVSCROLL are always automatically added to our styles, there is no need to specify it explicitly. @param parent - The parent window, must not be @NULL - + The parent window, must not be @NULL @param id - The identifier of this window, wxID_ANY by default - + The identifier of this window, wxID_ANY by default @param pos - The initial window position - + The initial window position @param size - The initial window size - + The initial window size @param style - The window style. There are no special style bits defined for - this class. - + The window style. There are no special style bits defined for + this class. @param name - The name for this window; usually not used + The name for this window; usually not used */ wxHVScrolledWindow(); wxHVScrolledWindow(wxWindow* parent, @@ -652,7 +625,6 @@ public: Same as the @ref wxhvscrolledwindow() "non-default constuctor" but returns status code: @true if ok, @false if the window couldn't be created. - Just as with the constructor above, the @c wxHSCROLL and @c wxVSCROLL styles are always used, there is no need to specify it explicitly. */ @@ -709,18 +681,19 @@ public: account for the new scroll position. @param vscrolling - Specifies if physical scrolling should be turned on when scrolling vertically. - + Specifies if physical scrolling should be turned on when scrolling + vertically. @param hscrolling - Specifies if physical scrolling should be turned on when scrolling horizontally. + Specifies if physical scrolling should be turned on when scrolling + horizontally. */ - void EnablePhysicalScrolling(bool vscrolling = @true, - bool hscrolling = @true); + void EnablePhysicalScrolling(bool vscrolling = true, + bool hscrolling = true); /** Returns the number of columns and rows the target window contains. - @sa SetRowColumnCount() + @see SetRowColumnCount() */ wxSize GetRowColumnCount(); @@ -840,28 +813,22 @@ public: /** This is the normal constructor, no need to call @c Create() after using this one. - Note that @c wxHSCROLL is always automatically added to our style, there is no need to specify it explicitly. @param parent - The parent window, must not be @NULL - + The parent window, must not be @NULL @param id - The identifier of this window, wxID_ANY by default - + The identifier of this window, wxID_ANY by default @param pos - The initial window position - + The initial window position @param size - The initial window size - + The initial window size @param style - The window style. There are no special style bits defined for - this class. - + The window style. There are no special style bits defined for + this class. @param name - The name for this window; usually not used + The name for this window; usually not used */ wxHScrolledWindow(); wxHScrolledWindow(wxWindow* parent, wxWindowID id = wxID_ANY, @@ -875,7 +842,6 @@ public: Same as the @ref wxhscrolledwindow() "non-default constuctor" but returns status code: @true if ok, @false if the window couldn't be created. - Just as with the constructor above, the @c wxHSCROLL style is always used, there is no need to specify it explicitly. */ diff --git a/interface/weakref.h b/interface/weakref.h index aa567a652e..4041dd0d06 100644 --- a/interface/weakref.h +++ b/interface/weakref.h @@ -67,7 +67,7 @@ public: /** Constructor. The weak reference is initialized to @e pobj. */ - wxWeakRefT(T* pobj = @NULL); + wxWeakRefT(T* pobj = NULL); /** Destructor. @@ -88,7 +88,7 @@ public: /** Returns pointer to the tracked object or @NULL. */ - T * get(); + T* get(); /** Release currently tracked object and start tracking the same object as diff --git a/interface/wfstream.h b/interface/wfstream.h index 130e169da7..b9bc3e7e6a 100644 --- a/interface/wfstream.h +++ b/interface/wfstream.h @@ -27,7 +27,6 @@ public: Associates wxTempFileOutputStream with the file to be replaced and opens it. You should use wxStreamBase::IsOk to verify if the constructor succeeded. - Call Commit() or wxOutputStream::Close to replace the old file and close this one. Calling Discard() (or allowing the destructor to do it) will discard the changes. @@ -78,9 +77,9 @@ public: Initializes a file stream in write-only mode using the file descriptor @e fp. */ wxFFileOutputStream(const wxString& filename, - const wxString& mode="w+b"); + const wxString& mode = "w+b"); wxFFileOutputStream(wxFFile& file); - wxFFileOutputStream(FILE * fp); + wxFFileOutputStream(FILE* fp); //@} /** @@ -91,7 +90,7 @@ public: /** Returns @true if the stream is initialized and ready. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); }; @@ -134,7 +133,7 @@ public: /** Returns @true if the stream is initialized and ready. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); }; @@ -177,7 +176,7 @@ public: /** Returns @true if the stream is initialized and ready. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); }; @@ -211,7 +210,7 @@ public: wxFFileInputStream(const wxString& filename, const wxString& mode = "rb"); wxFFileInputStream(wxFFile& file); - wxFFileInputStream(FILE * fp); + wxFFileInputStream(FILE* fp); //@} /** @@ -222,7 +221,7 @@ public: /** Returns @true if the stream is initialized and ready. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); }; diff --git a/interface/window.h b/interface/window.h index cf151d8871..31ff77b150 100644 --- a/interface/window.h +++ b/interface/window.h @@ -130,8 +130,8 @@ @category{FIXME} @seealso - @ref overview_eventhandlingoverview "Event handling overview", @ref - overview_windowsizingoverview "Window sizing overview" + @ref overview_eventhandlingoverview, @ref overview_windowsizingoverview "Window + sizing overview" */ class wxWindow : public wxEvtHandler { @@ -142,30 +142,25 @@ public: non-control window. @param parent - Pointer to a parent window. - + Pointer to a parent window. @param id - Window identifier. If wxID_ANY, will automatically create an identifier. - + Window identifier. If wxID_ANY, will automatically create an identifier. @param pos - Window position. wxDefaultPosition indicates that wxWidgets - should generate a default position for the window. If using the wxWindow class - directly, supply - an actual position. - + Window position. wxDefaultPosition indicates that wxWidgets + should generate a default position for the window. If using the wxWindow + class directly, supply + an actual position. @param size - Window size. wxDefaultSize indicates that wxWidgets - should generate a default size for the window. If no suitable size can be + Window size. wxDefaultSize indicates that wxWidgets + should generate a default size for the window. If no suitable size can be found, the - window will be sized to 20x20 pixels so that the window is visible but + window will be sized to 20x20 pixels so that the window is visible but obviously not - correctly sized. - + correctly sized. @param style - Window style. For generic window styles, please see wxWindow. - + Window style. For generic window styles, please see wxWindow. @param name - Window name. + Window name. */ wxWindow(); wxWindow(wxWindow* parent, wxWindowID id, @@ -181,8 +176,8 @@ public: use Destroy() so that wxWidgets can delete a window only when it is safe to do so, in idle time. - @sa @ref overview_windowdeletionoverview "Window deletion overview", - Destroy(), wxCloseEvent + @see @ref overview_windowdeletionoverview "Window deletion overview", + Destroy(), wxCloseEvent */ ~wxWindow(); @@ -191,7 +186,7 @@ public: indicate that this control doesn't accept input at all (i.e. behaves like e.g. wxStaticText) and so doesn't need focus. - @sa AcceptsFocusFromKeyboard() + @see AcceptsFocusFromKeyboard() */ bool AcceptsFocus(); @@ -206,26 +201,23 @@ public: /** Adds a child window. This is called automatically by window creation functions so should not be required by the application programmer. - Notice that this function is mostly internal to wxWidgets and shouldn't be called by the user code. @param child - Child window to add. + Child window to add. */ virtual void AddChild(wxWindow* child); /** Call this function to force one or both scrollbars to be always shown, even if the window is big enough to show its entire contents without scrolling. - This function is new since wxWidgets version 2.9.0 @param hflag - Whether the horizontal scroll bar should always be visible. - + Whether the horizontal scroll bar should always be visible. @param vflag - Whether the vertical scroll bar should always be visible. + Whether the vertical scroll bar should always be visible. @remarks This function is currently only implemented under Mac/Carbon. */ @@ -248,20 +240,18 @@ public: /** Directs all mouse input to this window. Call ReleaseMouse() to release the capture. - Note that wxWidgets maintains the stack of windows having captured the mouse and when the mouse is released the capture returns to the window which had had captured it previously and it is only really released if there were no previous window. In particular, this means that you must release the mouse as many times as you capture it, unless the window receives the wxMouseCaptureLostEvent event. - Any application which captures the mouse in the beginning of some operation must handle wxMouseCaptureLostEvent and cancel this operation when it receives the event. The event handler must not recapture mouse. - @sa ReleaseMouse(), wxMouseCaptureLostEvent + @see ReleaseMouse(), wxMouseCaptureLostEvent */ virtual void CaptureMouse(); @@ -279,15 +269,15 @@ public: Centres the window. @param direction - Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL - or wxBOTH. It may also include wxCENTRE_ON_SCREEN flag - if you want to center the window on the entire screen and not on its - parent window. + Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL + or wxBOTH. It may also include wxCENTRE_ON_SCREEN flag + if you want to center the window on the entire screen and not on its + parent window. @remarks If the window is a top level one (i.e. doesn't have a parent), - it will be centered relative to the screen anyhow. + it will be centered relative to the screen anyhow. - @sa Center() + @see Center() */ void Centre(int direction = wxBOTH); @@ -296,16 +286,15 @@ public: Centre(). @param direction - Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL - or wxBOTH. + Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL + or wxBOTH. @remarks This methods provides for a way to center top level windows over - their parents instead of the entire screen. If there - is no parent or if the window is not a top level - window, then behaviour is the same as - Centre(). + their parents instead of the entire screen. If there + is no parent or if the window is not a top level + window, then behaviour is the same as Centre(). - @sa wxTopLevelWindow::CentreOnScreen + @see wxTopLevelWindow::CentreOnScreen */ void CentreOnParent(int direction = wxBOTH); @@ -319,35 +308,31 @@ public: /** Converts to screen coordinates from coordinates relative to this window. - @param x - A pointer to a integer value for the x coordinate. Pass the client coordinate - in, and - a screen coordinate will be passed out. - + A pointer to a integer value for the x coordinate. Pass the client + coordinate in, and + a screen coordinate will be passed out. @param y - A pointer to a integer value for the y coordinate. Pass the client coordinate - in, and - a screen coordinate will be passed out. - + A pointer to a integer value for the y coordinate. Pass the client + coordinate in, and + a screen coordinate will be passed out. @param pt - The client position for the second form of the function. + The client position for the second form of the function. */ virtual void ClientToScreen(int* x, int* y); virtual wxPoint ClientToScreen(const wxPoint& pt); //@} /** - Converts client area size @e size to corresponding window size. In other + Converts client area size @a size to corresponding window size. In other words, the returned value is what would GetSize() return if this window had client area of given size. Components with wxDefaultCoord value are left unchanged. - Note that the conversion is not always exact, it assumes that non-client area doesn't change and so doesn't take into account things like menu bar (un)wrapping or (dis)appearance of the scrollbars. - @sa WindowToClientSize() + @see WindowToClientSize() */ virtual wxSize ClientToWindowSize(const wxSize& size); @@ -357,37 +342,34 @@ public: however. @param force - @false if the window's close handler should be able to veto the destruction - of this window, @true if it cannot. + @false if the window's close handler should be able to veto the destruction + of this window, @true if it cannot. @remarks Close calls the close handler for the window, providing an - opportunity for the window to choose whether to - destroy the window. Usually it is only used with the - top level windows (wxFrame and wxDialog classes) as - the others are not supposed to have any special - OnClose() logic. + opportunity for the window to choose whether to destroy + the window. Usually it is only used with the top level + windows (wxFrame and wxDialog classes) as the others + are not supposed to have any special OnClose() logic. - @sa @ref overview_windowdeletionoverview "Window deletion overview", - Destroy(), wxCloseEvent + @see @ref overview_windowdeletionoverview "Window deletion overview", + Destroy(), wxCloseEvent */ - bool Close(bool force = @false); + bool Close(bool force = false); //@{ /** Converts a point or size from dialog units to pixels. - For the x dimension, the dialog units are multiplied by the average character width and then divided by 4. - For the y dimension, the dialog units are multiplied by the average character height and then divided by 8. @remarks Dialog units are used for maintaining a dialog's proportions - even if the font changes. + even if the font changes. - @sa ConvertPixelsToDialog() + @see ConvertPixelsToDialog() */ wxPoint ConvertDialogToPixels(const wxPoint& pt); wxSize ConvertDialogToPixels(const wxSize& sz); @@ -396,19 +378,17 @@ public: //@{ /** Converts a point or size from pixels to dialog units. - For the x dimension, the pixels are multiplied by 4 and then divided by the average character width. - For the y dimension, the pixels are multiplied by 8 and then divided by the average character height. @remarks Dialog units are used for maintaining a dialog's proportions - even if the font changes. + even if the font changes. - @sa ConvertDialogToPixels() + @see ConvertDialogToPixels() */ wxPoint ConvertPixelsToDialog(const wxPoint& pt); wxSize ConvertPixelsToDialog(const wxSize& sz); @@ -425,8 +405,8 @@ public: windows. @returns @true if the window has either been successfully deleted, or it - has been added to the list of windows pending real - deletion. + has been added to the list of windows pending real + deletion. */ virtual bool Destroy(); @@ -439,8 +419,7 @@ public: Disables the window, same as @ref enable() Enable(@false). @returns Returns @true if the window has been disabled, @false if it had - been already disabled before the call to this - function. + been already disabled before the call to this function. */ bool Disable(); @@ -465,8 +444,8 @@ public: Enables or disables eligibility for drop file events (OnDropFiles). @param accept - If @true, the window is eligible for drop file events. If @false, the window - will not accept drop file events. + If @true, the window is eligible for drop file events. If @false, the window + will not accept drop file events. @remarks Windows only. */ @@ -478,23 +457,23 @@ public: when the parent is. @param enable - If @true, enables the window for input. If @false, disables the window. + If @true, enables the window for input. If @false, disables the window. @returns Returns @true if the window has been enabled or disabled, @false - if nothing was done, i.e. if the window had already - been in the specified state. + if nothing was done, i.e. if the window had already + been in the specified state. - @sa IsEnabled(), Disable(), wxRadioBox::Enable + @see IsEnabled(), Disable(), wxRadioBox::Enable */ - virtual bool Enable(bool enable = @true); + virtual bool Enable(bool enable = true); /** Finds the window or control which currently has the keyboard focus. @remarks Note that this is a static function, so it can be called without - needing a wxWindow pointer. + needing a wxWindow pointer. - @sa SetFocus(), HasFocus() + @see SetFocus(), HasFocus() */ static wxWindow* FindFocus(); @@ -508,45 +487,43 @@ public: /** Find the first window with the given @e id. - - If @e parent is @NULL, the search will start from all top-level + If @a parent is @NULL, the search will start from all top-level frames and dialog boxes; if non-@NULL, the search will be limited to the given window hierarchy. The search is recursive in both cases. - @sa FindWindow() + @see FindWindow() */ - static wxWindow* FindWindowById(long id, wxWindow* parent = @NULL); + static wxWindow* FindWindowById(long id, wxWindow* parent = NULL); /** Find a window by its label. Depending on the type of window, the label may be a window title - or panel item label. If @e parent is @NULL, the search will start from all + or panel item label. If @a parent is @NULL, the search will start from all top-level frames and dialog boxes; if non-@NULL, the search will be limited to the given window hierarchy. The search is recursive in both cases. - @sa FindWindow() + @see FindWindow() */ static wxWindow* FindWindowByLabel(const wxString& label, - wxWindow* parent = @NULL); + wxWindow* parent = NULL); /** Find a window by its name (as given in a window constructor or @b Create function call). - If @e parent is @NULL, the search will start from all top-level + If @a parent is @NULL, the search will start from all top-level frames and dialog boxes; if non-@NULL, the search will be limited to the given window hierarchy. The search is recursive in both cases. - If no window with such name is found, FindWindowByLabel() is called. - @sa FindWindow() + @see FindWindow() */ static wxWindow* FindWindowByName(const wxString& name, - wxWindow* parent = @NULL); + wxWindow* parent = NULL); /** Sizes the window so that it fits around its subwindows. This function won't do @@ -554,9 +531,10 @@ public: sizers are used for the subwindows layout. Also, if the window has exactly one subwindow it is better (faster and the result is more precise as Fit adds some margin to account for fuzziness of its calculations) to call + instead of calling Fit. */ -#define virtual void Fit() /* implementation is private */ + virtual void Fit(); /** Similar to Fit(), but sizes the interior (virtual) size @@ -573,14 +551,13 @@ public: be called to reenable window redrawing. Calls to these two functions may be nested but to ensure that the window is properly repainted again, you must thaw it exactly as many times as you froze it. - This method is useful for visual appearance optimization (for example, it is a good idea to use it before doing many large text insertions in a row into a wxTextCtrl under wxGTK) but is not implemented on all platforms nor for all controls so it is mostly just a hint to wxWidgets and not a mandatory directive. - @sa wxWindowUpdateLocker + @see wxWindowUpdateLocker */ virtual void Freeze(); @@ -591,7 +568,6 @@ public: /** Returns the accessible object for this window, if any. - See also wxAccessible. */ wxAccessible* GetAccessible(); @@ -605,24 +581,21 @@ public: /** Returns the background colour of the window. - @sa SetBackgroundColour(), SetForegroundColour(), - GetForegroundColour() + @see SetBackgroundColour(), SetForegroundColour(), + GetForegroundColour() */ virtual wxColour GetBackgroundColour(); /** Returns the background style of the window. The background style can be one of: - wxBG_STYLE_SYSTEM - Use the default background, as determined by the system or the current theme. wxBG_STYLE_COLOUR - Use a solid colour for the background, this style is set automatically if you call SetBackgroundColour() so you only need to @@ -631,7 +604,6 @@ public: wxBG_STYLE_CUSTOM - Don't draw the background at all, it's supposed that it is drawn by the user-defined erase background event handler. This style should be used to avoid flicker when the background is entirely @@ -639,15 +611,13 @@ public: wxBG_STYLE_TRANSPARET - The background is (partially) transparent, this style is automatically set if you call SetTransparent() which is used to set the transparency level. - - @sa SetBackgroundColour(), GetForegroundColour(), - SetBackgroundStyle(), SetTransparent() + @see SetBackgroundColour(), GetForegroundColour(), + SetBackgroundStyle(), SetTransparent() */ virtual wxBackgroundStyle GetBackgroundStyle(); @@ -664,15 +634,15 @@ public: /** Returns the currently captured window. - @sa HasCapture(), CaptureMouse(), ReleaseMouse(), - wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent + @see HasCapture(), CaptureMouse(), ReleaseMouse(), + wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent */ - static wxWindow * GetCapture(); + static wxWindow* GetCapture(); /** Returns the caret associated with the window. */ - wxCaret * GetCaret(); + wxCaret* GetCaret(); /** Returns the character height for this window. @@ -700,24 +670,21 @@ public: standard control -- which is a much better idea than hard coding specific colours or fonts which might look completely out of place on the users system, especially if it uses themes. - - The @e variant parameter is only relevant under Mac currently and is + The @a variant parameter is only relevant under Mac currently and is ignore under other platforms. Under Mac, it will change the size of the returned font. See SetWindowVariant() for more about this. - This static method is "overridden'' in many derived classes and so calling, for example, wxButton::GetClassDefaultAttributes() will typically return the values appropriate for a button which will be normally different from those returned by, say, wxListCtrl::GetClassDefaultAttributes(). - The @c wxVisualAttributes structure has at least the fields @c font, @c colFg and @c colBg. All of them may be invalid if it was not possible to determine the default control appearance or, especially for the background colour, if the field doesn't make sense as is the case for @c colBg for the controls with themed background. - @sa InheritAttributes() + @see InheritAttributes() */ static wxVisualAttributes GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL); @@ -726,17 +693,15 @@ public: Returns the size of the window 'client area' in pixels. The client area is the area which may be drawn on by the programmer, excluding title bar, border, scrollbars, etc. - Note that if this window is a top-level one and it is currently minimized, the return size is empty (both width and height are 0). @param width - Receives the client width in pixels. - + Receives the client width in pixels. @param height - Receives the client height in pixels. + Receives the client height in pixels. - @sa GetSize(), GetVirtualSize() + @see GetSize(), GetVirtualSize() */ void GetClientSize(int* width, int* height); wxSize GetClientSize(); @@ -751,23 +716,21 @@ public: Return the sizer that this window is a member of, if any, otherwise @NULL. */ - const wxSizer * GetContainingSizer(); + const wxSizer* GetContainingSizer(); /** Return the cursor associated with this window. - @sa SetCursor() + @see SetCursor() */ const wxCursor GetCursor(); /** Currently this is the same as calling wxWindow::GetClassDefaultAttributes(wxWindow::GetWindowVariant()). - One advantage of using this function compared to the static version is that the call is automatically dispatched to the correct class (as usual with virtual functions) and you don't have to specify the class name explicitly. - The other one is that in the future this function could return different results, for example it might return a different font for an "Ok'' button than for a generic button if the users GUI is configured to show such buttons @@ -780,8 +743,7 @@ public: /** Returns the associated drop target, which may be @NULL. - @sa SetDropTarget(), @ref overview_wxdndoverview "Drag and drop - overview" + @see SetDropTarget(), @ref overview_wxdndoverview */ wxDropTarget* GetDropTarget(); @@ -790,7 +752,7 @@ public: result. This is the value used by sizers to determine the appropriate ammount of space to allocate for the widget. - @sa GetBestSize(), SetInitialSize() + @see GetBestSize(), SetInitialSize() */ wxSize GetEffectiveMinSize(); @@ -798,8 +760,8 @@ public: Returns the event handler for this window. By default, the window is its own event handler. - @sa SetEventHandler(), PushEventHandler(), - PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler + @see SetEventHandler(), PushEventHandler(), + PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler */ wxEvtHandler* GetEventHandler(); @@ -811,7 +773,7 @@ public: /** Returns the font for this window. - @sa SetFont() + @see SetFont() */ wxFont GetFont(); @@ -819,12 +781,12 @@ public: Returns the foreground colour of the window. @remarks The interpretation of foreground colour is open to - interpretation according to the window class; it may - be the text colour or other colour, or it may not be - used at all. + interpretation according to the window class; it may be + the text colour or other colour, or it may not be used + at all. - @sa SetForegroundColour(), SetBackgroundColour(), - GetBackgroundColour() + @see SetForegroundColour(), SetBackgroundColour(), + GetBackgroundColour() */ virtual wxColour GetForegroundColour(); @@ -843,12 +805,11 @@ public: /** Gets the help text to be used as context-sensitive help for this window. - Note that the text is actually stored by the current wxHelpProvider implementation, and not in the window object itself. - @sa SetHelpText(), GetHelpTextAtPoint(), wxHelpProvider + @see SetHelpText(), GetHelpTextAtPoint(), wxHelpProvider */ virtual wxString GetHelpText(); @@ -858,10 +819,9 @@ public: the window, otherwise GetHelpText() can be used. @param point - Coordinates of the mouse at the moment of help event emission. - + Coordinates of the mouse at the moment of help event emission. @param origin - Help event origin, see also wxHelpEvent::GetOrigin. + Help event origin, see also wxHelpEvent::GetOrigin. */ virtual wxString GetHelpTextAtPoint(const wxPoint point, wxHelpEvent::Origin origin); @@ -870,10 +830,10 @@ public: Returns the identifier of the window. @remarks Each window has an integer identifier. If the application has - not provided one (or the default wxID_ANY) an unique - identifier with a negative value will be generated. + not provided one (or the default wxID_ANY) an unique + identifier with a negative value will be generated. - @sa SetId(), @ref overview_windowids "Window identifiers" + @see SetId(), @ref overview_windowids "Window identifiers" */ int GetId(); @@ -882,12 +842,11 @@ public: identification purposes. @remarks The interpretation of this function differs from class to class. - For frames and dialogs, the value returned is the - title. For buttons or static text controls, it is the - button text. This function can be useful for - meta-programs (such as testing tools or special-needs - access programs) which need to identify windows by - name. + For frames and dialogs, the value returned is the + title. For buttons or static text controls, it is the + button text. This function can be useful for + meta-programs (such as testing tools or special-needs + access programs) which need to identify windows by name. */ virtual wxString GetLabel(); @@ -897,7 +856,7 @@ public: possible size as well as the upper bound on window's size settable using SetClientSize(). - @sa GetMaxSize() + @see GetMaxSize() */ wxSize GetMaxClientSize(); @@ -906,7 +865,7 @@ public: layout mechanism that this is the maximum possible size as well as the upper bound on window's size settable using SetSize(). - @sa GetMaxClientSize() + @see GetMaxClientSize() */ wxSize GetMaxSize(); @@ -917,7 +876,7 @@ public: SetMinClientSize(), but it can be overridden to do the calculation on demand. - @sa GetMinSize() + @see GetMinSize() */ virtual wxSize GetMinClientSize(); @@ -928,7 +887,7 @@ public: by SetMinSize(), but it can be overridden to do the calculation on demand. - @sa GetMinClientSize() + @see GetMinClientSize() */ virtual wxSize GetMinSize(); @@ -936,22 +895,21 @@ public: Returns the window's name. @remarks This name is not guaranteed to be unique; it is up to the - programmer to supply an appropriate name in the - window constructor or via SetName(). + programmer to supply an appropriate name in the window + constructor or via SetName(). - @sa SetName() + @see SetName() */ virtual wxString GetName(); /** Returns the next window after this one among the parent children or @NULL if this window is the last child. - This function is new since wxWidgets version 2.8.8 - @sa GetPrevSibling() + @see GetPrevSibling() */ - wxWindow * GetNextSibling(); + wxWindow* GetNextSibling(); /** Returns the parent of the window, or @NULL if there is no parent. @@ -966,19 +924,16 @@ public: choice in a list of strings to the user. @param menu - The menu to show - + The menu to show @param pos - The position at which to show the menu in client coordinates - + The position at which to show the menu in client coordinates @param x - The horizontal position of the menu - + The horizontal position of the menu @param y - The vertical position of the menu + The vertical position of the menu @returns The selected menu item id or wxID_NONE if none selected or an - error occurred. + error occurred. */ int GetPopupMenuSelectionFromUser(wxMenu& menu, const wxPoint& pos); @@ -992,12 +947,11 @@ public: windows. @param x - Receives the x position of the window if non-@NULL. - + Receives the x position of the window if non-@NULL. @param y - Receives the y position of the window if non-@NULL. + Receives the y position of the window if non-@NULL. - @sa GetScreenPosition() + @see GetScreenPosition() */ virtual void GetPosition(int* x, int* y); wxPoint GetPosition(); @@ -1007,17 +961,16 @@ public: Returns the previous window before this one among the parent children or @c @NULL if this window is the first child. - This function is new since wxWidgets version 2.8.8 - @sa GetNextSibling() + @see GetNextSibling() */ - wxWindow * GetPrevSibling(); + wxWindow* GetPrevSibling(); /** Returns the position and size of the window as a wxRect object. - @sa GetScreenRect() + @see GetScreenRect() */ virtual wxRect GetRect(); @@ -1027,12 +980,11 @@ public: child window or a top level one. @param x - Receives the x position of the window on the screen if non-@NULL. - + Receives the x position of the window on the screen if non-@NULL. @param y - Receives the y position of the window on the screen if non-@NULL. + Receives the y position of the window on the screen if non-@NULL. - @sa GetPosition() + @see GetPosition() */ virtual void GetScreenPosition(int* x, int* y); wxPoint GetScreenPosition(); @@ -1042,28 +994,28 @@ public: Returns the position and size of the window on the screen as a wxRect object. - @sa GetRect() + @see GetRect() */ virtual wxRect GetScreenRect(); /** Returns the built-in scrollbar position. - @sa See SetScrollbar() + @see See SetScrollbar() */ virtual int GetScrollPos(int orientation); /** Returns the built-in scrollbar range. - @sa SetScrollbar() + @see SetScrollbar() */ virtual int GetScrollRange(int orientation); /** Returns the built-in scrollbar thumb size. - @sa SetScrollbar() + @see SetScrollbar() */ virtual int GetScrollThumb(int orientation); @@ -1071,17 +1023,15 @@ public: /** Returns the size of the entire window in pixels, including title bar, border, scrollbars, etc. - Note that if this window is a top-level one and it is currently minimized, the returned size is the restored window size, not the size of the window icon. @param width - Receives the window width. - + Receives the window width. @param height - Receives the window height. + Receives the window height. - @sa GetClientSize(), GetVirtualSize() + @see GetClientSize(), GetVirtualSize() */ void GetSize(int* width, int* height); wxSize GetSize(); @@ -1091,43 +1041,36 @@ public: Return the sizer associated with the window by a previous call to SetSizer() or @NULL. */ - wxSizer * GetSizer(); + wxSizer* GetSizer(); //@{ /** Gets the dimensions of the string as it would be drawn on the window with the currently selected font. - - The text extent is returned in @e w and @e h pointers (first form) or as a + The text extent is returned in @a w and @a h pointers (first form) or as a wxSize object (second form). @param string - String whose extent is to be measured. - + String whose extent is to be measured. @param w - Return value for width. - + Return value for width. @param h - Return value for height. - + Return value for height. @param descent - Return value for descent (optional). - + Return value for descent (optional). @param externalLeading - Return value for external leading (optional). - + Return value for external leading (optional). @param font - Font to use instead of the current window font (optional). - + Font to use instead of the current window font (optional). @param use16 - If @true, string contains 16-bit characters. The default is @false. + If @true, string contains 16-bit characters. The default is @false. */ virtual void GetTextExtent(const wxString& string, int* w, int* h, - int* descent = @NULL, - int* externalLeading = @NULL, - const wxFont* font = @NULL, - bool use16 = @false); + int* descent = NULL, + int* externalLeading = NULL, + const wxFont* font = NULL, + bool use16 = false); wxSize GetTextExtent(const wxString& string); //@} @@ -1141,7 +1084,7 @@ public: Should only be called within an wxPaintEvent handler. - @sa wxRegion, wxRegionIterator + @see wxRegion, wxRegionIterator */ virtual wxRegion GetUpdateRegion(); @@ -1159,10 +1102,9 @@ public: that size. @param width - Receives the window virtual width. - + Receives the window virtual width. @param height - Receives the window virtual height. + Receives the window virtual height. */ void GetVirtualSize(int* width, int* height); wxSize GetVirtualSize(); @@ -1192,9 +1134,9 @@ public: keyboard navigation and return @true in this case. @returns Returns @true if the key pressed was for navigation and was - handled, @false otherwise. + handled, @false otherwise. - @sa Navigate() + @see Navigate() */ bool HandleAsNavigationKey(const wxKeyEvent& event); @@ -1207,21 +1149,21 @@ public: /** Returns @true if this window has the current mouse capture. - @sa CaptureMouse(), ReleaseMouse(), wxMouseCaptureLostEvent, - wxMouseCaptureChangedEvent + @see CaptureMouse(), ReleaseMouse(), wxMouseCaptureLostEvent, + wxMouseCaptureChangedEvent */ virtual bool HasCapture(); /** - Returns @true if the window has the given @e exFlag bit set in its + Returns @true if the window has the given @a exFlag bit set in its extra styles. - @sa SetExtraStyle() + @see SetExtraStyle() */ bool HasExtraStyle(int exFlag); /** - Returns @true if the window has the given @e flag bit set. + Returns @true if the window has the given @a flag bit set. */ bool HasFlag(int flag); @@ -1229,7 +1171,7 @@ public: Returns @true if the window (or in case of composite controls, its main child window) has focus. - @sa FindFocus() + @see FindFocus() */ virtual bool HasFocus(); @@ -1247,14 +1189,13 @@ public: Returns @true if this window has a scroll bar for this orientation. @param orient - Orientation to check, either wxHORIZONTAL or wxVERTICAL. + Orientation to check, either wxHORIZONTAL or wxVERTICAL. */ virtual bool HasScrollbar(int orient); /** Returns @true if this window background is transparent (as, for example, for wxStaticText) and should show the parent window background. - This method is mostly used internally by the library itself and you normally shouldn't have to call it. You may, however, have to override it in your wxWindow-derived class to ensure that background is painted correctly. @@ -1269,11 +1210,9 @@ public: /** This function hides a window, like Hide(), but using a special visual effect if possible. - The parameters of this function are the same as for ShowWithEffect(), please see their description there. - This function is new since wxWidgets version 2.9.0 */ virtual bool HideWithEffect(wxShowEffect effect, @@ -1284,7 +1223,6 @@ public: This function is (or should be, in case of custom controls) called during window creation to intelligently set up the window visual attributes, that is the font and the foreground and background colours. - By "intelligently'' the following is meant: by default, all windows use their own @ref getclassdefaultattributes() default attributes. However if some of the parents attributes are explicitly (that is, using @@ -1295,7 +1233,6 @@ public: the window overrides ShouldInheritColours() to return @false, the colours will not be changed no matter what and only the font might. - This rather complicated logic is necessary in order to accommodate the different usage scenarios. The most common one is when all default attributes are used and in this case, nothing should be inherited as in modern GUIs @@ -1324,7 +1261,7 @@ public: any drawing done on the window is really done on a temporary backing surface and transferred to the screen all at once later. - @sa wxBufferedDC + @see wxBufferedDC */ virtual bool IsDoubleBuffered(); @@ -1332,13 +1269,12 @@ public: Returns @true if the window is enabled, i.e. if it accepts user input, @c @false otherwise. - Notice that this method can return @false even if this window itself hadn't been explicitly disabled when one of its parent windows is disabled. To get the intrinsic status of this window, use IsThisEnabled() - @sa Enable() + @see Enable() */ virtual bool IsEnabled(); @@ -1358,7 +1294,7 @@ public: Returns @true if the window is currently frozen by a call to Freeze(). - @sa Thaw() + @see Thaw() */ virtual bool IsFrozen(); @@ -1373,16 +1309,16 @@ public: Return whether a scrollbar is always shown. @param orient - Orientation to check, either wxHORIZONTAL or wxVERTICAL. + Orientation to check, either wxHORIZONTAL or wxVERTICAL. - @sa AlwaysShowScrollbars() + @see AlwaysShowScrollbars() */ bool IsScrollbarAlwaysShown(int orient); /** Returns @true if the window is shown, @false if it has been hidden. - @sa IsShownOnScreen() + @see IsShownOnScreen() */ virtual bool IsShown(); @@ -1390,7 +1326,7 @@ public: Returns @true if the window is physically visible on the screen, i.e. it is shown and all its parents up to the toplevel window are shown as well. - @sa IsShown() + @see IsShown() */ virtual bool IsShownOnScreen(); @@ -1413,7 +1349,6 @@ public: /** Invokes the constraint-based layout algorithm or the sizer-based algorithm for this window. - See SetAutoLayout(): when auto layout is on, this function gets called automatically when the window is resized. @@ -1433,7 +1368,7 @@ public: /** Lowers the window to the bottom of the window hierarchy (Z-order). - @sa Raise() + @see Raise() */ void Lower(); @@ -1442,8 +1377,9 @@ public: the user can only interact with this window. @param flag - If @true, this call disables all other windows in the application so that - the user can only interact with this window. If @false, the effect is reversed. + If @true, this call disables all other windows in the application so that + the user can only interact with this window. If @false, the effect is + reversed. */ virtual void MakeModal(bool flag); @@ -1452,19 +1388,17 @@ public: Moves the window to the given position. @param x - Required x position. - + Required x position. @param y - Required y position. - + Required y position. @param pt - wxPoint object representing the position. + wxPoint object representing the position. @remarks Implementations of SetSize can also implicitly implement the - Move() function, which is defined in the base - wxWindow class as the call: + Move() function, which is defined in the base + wxWindow class as the call: - @sa SetSize() + @see SetSize() */ void Move(int x, int y); void Move(const wxPoint& pt); @@ -1474,23 +1408,22 @@ public: Moves this window in the tab navigation order after the specified @e win. This means that when the user presses @c TAB key on that other window, the focus switches to this window. - Default tab order is the same as creation order, this function and MoveBeforeInTabOrder() allow to change it after creating all the windows. @param win - A sibling of this window which should precede it in tab order, - must not be @NULL + A sibling of this window which should precede it in tab order, + must not be @NULL */ - void MoveAfterInTabOrder(wxWindow * win); + void MoveAfterInTabOrder(wxWindow* win); /** Same as MoveAfterInTabOrder() except that - it inserts this window just before @e win instead of putting it right after + it inserts this window just before @a win instead of putting it right after it. */ - void MoveBeforeInTabOrder(wxWindow * win); + void MoveBeforeInTabOrder(wxWindow* win); /** Performs a keyboard navigation action starting from this window. This method is @@ -1498,25 +1431,24 @@ public: parent window. @param flags - A combination of wxNavigationKeyEvent::IsForward and + A combination of wxNavigationKeyEvent::IsForward and wxNavigationKeyEvent::WinChange. @returns Returns @true if the focus was moved to another window or @false - if nothing changed. + if nothing changed. @remarks You may wish to call this from a text control custom keypress - handler to do the default navigation behaviour for - the tab key, since the standard default behaviour for - a multiline text control with the wxTE_PROCESS_TAB - style is to insert a tab and not navigate to the next - control. See also wxNavigationKeyEvent and - HandleAsNavigationKey. + handler to do the default navigation behaviour for the + tab key, since the standard default behaviour for a + multiline text control with the wxTE_PROCESS_TAB style + is to insert a tab and not navigate to the next + control. See also wxNavigationKeyEvent and + HandleAsNavigationKey. */ bool Navigate(int flags = wxNavigationKeyEvent::IsForward); /** Performs a keyboard navigation action inside this window. - See Navigate() for more information. */ bool NavigateIn(int flags = wxNavigationKeyEvent::IsForward); @@ -1525,17 +1457,16 @@ public: Create a new ID or range of IDs that are not currently in use. The IDs will be reserved until assigned to a wxWindowIDRef or unreserved with UnreserveControlId(). - See @ref overview_windowidsoverview "Window IDs overview" for more information. @param count - The number of sequential IDs to reserve. + The number of sequential IDs to reserve. @returns Returns the ID or the first ID of the range, or wxID_NONE if the - specified number of identifiers couldn't be allocated. + specified number of identifiers couldn't be allocated. - @sa UnreserveControlId(), wxIdManager, @ref overview_windowidsoverview - "Window IDs overview" + @see UnreserveControlId(), wxIdManager, @ref overview_windowidsoverview + "Window IDs overview" */ static wxWindowID NewControlId(int count = 1); @@ -1544,7 +1475,6 @@ public: sometimes an application may need it to implement functionality that should not be disabled by an application defining an OnIdle handler in a derived class. - This function may be used to do delayed painting, for example, and most implementations call UpdateWindowUI() in order to send update events to the window in idle time. @@ -1565,13 +1495,13 @@ public: Removes and returns the top-most event handler on the event handler stack. @param deleteHandler - If this is @true, the handler will be deleted after it is removed. The - default value is @false. + If this is @true, the handler will be deleted after it is removed. The + default value is @false. - @sa SetEventHandler(), GetEventHandler(), - PushEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler + @see SetEventHandler(), GetEventHandler(), + PushEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler */ - wxEvtHandler* PopEventHandler(bool deleteHandler = @false); + wxEvtHandler* PopEventHandler(bool deleteHandler = false); //@{ /** @@ -1582,22 +1512,19 @@ public: cursor position is used. @param menu - Menu to pop up. - + Menu to pop up. @param pos - The position where the menu will appear. - + The position where the menu will appear. @param x - Required x position for the menu to appear. - + Required x position for the menu to appear. @param y - Required y position for the menu to appear. + Required y position for the menu to appear. @remarks Just before the menu is popped up, wxMenu::UpdateUI is called to - ensure that the menu items are in the correct state. - The menu does not get deleted by the window. + ensure that the menu items are in the correct state. + The menu does not get deleted by the window. - @sa wxMenu + @see wxMenu */ bool PopupMenu(wxMenu* menu, const wxPoint& pos = wxDefaultPosition); @@ -1608,26 +1535,25 @@ public: Pushes this event handler onto the event stack for the window. @param handler - Specifies the handler to be pushed. + Specifies the handler to be pushed. @remarks An event handler is an object that is capable of processing the - events sent to a window. By default, the window is - its own event handler, but an application may wish to - substitute another, for example to allow central - implementation of event-handling for a variety of - different window classes. + events sent to a window. By default, the window is its + own event handler, but an application may wish to + substitute another, for example to allow central + implementation of event-handling for a variety of + different window classes. - @sa SetEventHandler(), GetEventHandler(), - PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler + @see SetEventHandler(), GetEventHandler(), + PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler */ void PushEventHandler(wxEvtHandler* handler); /** Raises the window to the top of the window hierarchy (Z-order). - In current version of wxWidgets this works both for managed and child windows. - @sa Lower() + @see Lower() */ void Raise(); @@ -1639,27 +1565,25 @@ public: instead. @param eraseBackground - If @true, the background will be - erased. - + If @true, the background will be + erased. @param rect - If non-@NULL, only the given rectangle will - be treated as damaged. + If non-@NULL, only the given rectangle will + be treated as damaged. - @sa RefreshRect() + @see RefreshRect() */ - virtual void Refresh(bool eraseBackground = @true, - const wxRect* rect = @NULL); + virtual void Refresh(bool eraseBackground = true, + const wxRect* rect = NULL); /** Redraws the contents of the given rectangle: only the area inside it will be repainted. - This is the same as Refresh() but has a nicer syntax as it can be called with a temporary wxRect object as argument like this @c RefreshRect(wxRect(x, y, w, h)). */ - void RefreshRect(const wxRect& rect, bool eraseBackground = @true); + void RefreshRect(const wxRect& rect, bool eraseBackground = true); /** Registers a system wide hotkey. Every time the user presses the hotkey @@ -1670,30 +1594,28 @@ public: application. @param hotkeyId - Numeric identifier of the hotkey. For applications this must be between 0 and - 0xBFFF. If - this function is called from a shared DLL, it must be a system wide unique + Numeric identifier of the hotkey. For applications this must be between 0 + and 0xBFFF. If + this function is called from a shared DLL, it must be a system wide unique identifier between 0xC000 and 0xFFFF. - This is a MSW specific detail. - + This is a MSW specific detail. @param modifiers - A bitwise combination of wxMOD_SHIFT, wxMOD_CONTROL, wxMOD_ALT - or wxMOD_WIN specifying the modifier keys that have to be pressed along with - the key. - + A bitwise combination of wxMOD_SHIFT, wxMOD_CONTROL, wxMOD_ALT + or wxMOD_WIN specifying the modifier keys that have to be pressed along + with the key. @param virtualKeyCode - The virtual key code of the hotkey. + The virtual key code of the hotkey. @returns @true if the hotkey was registered successfully. @false if some - other application already registered a hotkey with - this modifier/virtualKeyCode combination. + other application already registered a hotkey with this + modifier/virtualKeyCode combination. @remarks Use EVT_HOTKEY(hotkeyId, fnc) in the event table to capture the - event. This function is currently only implemented - under Windows. It is used in the Windows CE port for - detecting hardware button presses. + event. This function is currently only implemented + under Windows. It is used in the Windows CE port for + detecting hardware button presses. - @sa UnregisterHotKey() + @see UnregisterHotKey() */ bool RegisterHotKey(int hotkeyId, int modifiers, int virtualKeyCode); @@ -1701,39 +1623,38 @@ public: /** Releases mouse input captured with CaptureMouse(). - @sa CaptureMouse(), HasCapture(), ReleaseMouse(), - wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent + @see CaptureMouse(), HasCapture(), ReleaseMouse(), + wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent */ virtual void ReleaseMouse(); /** Removes a child window. This is called automatically by window deletion functions so should not be required by the application programmer. - Notice that this function is mostly internal to wxWidgets and shouldn't be called by the user code. @param child - Child window to remove. + Child window to remove. */ virtual void RemoveChild(wxWindow* child); /** - Find the given @e handler in the windows event handler chain and remove (but + Find the given @a handler in the windows event handler chain and remove (but not delete) it from it. @param handler - The event handler to remove, must be non-@NULL and - must be present in this windows event handlers chain + The event handler to remove, must be non-@NULL and + must be present in this windows event handlers chain @returns Returns @true if it was found and @false otherwise (this also - results in an assert failure so this function should - only be called when the handler is supposed to be - there). + results in an assert failure so this function should + only be called when the handler is supposed to be + there). - @sa PushEventHandler(), PopEventHandler() + @see PushEventHandler(), PopEventHandler() */ - bool RemoveEventHandler(wxEvtHandler * handler); + bool RemoveEventHandler(wxEvtHandler* handler); /** Reparents the window, i.e the window will be removed from its @@ -1741,7 +1662,7 @@ public: and then re-inserted into another. @param newParent - New parent. + New parent. */ virtual bool Reparent(wxWindow* newParent); @@ -1750,43 +1671,41 @@ public: Converts from screen to client window coordinates. @param x - Stores the screen x coordinate and receives the client x coordinate. - + Stores the screen x coordinate and receives the client x coordinate. @param y - Stores the screen x coordinate and receives the client x coordinate. - + Stores the screen x coordinate and receives the client x coordinate. @param pt - The screen position for the second form of the function. + The screen position for the second form of the function. */ virtual void ScreenToClient(int* x, int* y); virtual wxPoint ScreenToClient(const wxPoint& pt); //@} /** - Scrolls the window by the given number of lines down (if @e lines is + Scrolls the window by the given number of lines down (if @a lines is positive) or up. @returns Returns @true if the window was scrolled, @false if it was already - on top/bottom and nothing was done. + on top/bottom and nothing was done. @remarks This function is currently only implemented under MSW and - wxTextCtrl under wxGTK (it also works for - wxScrolledWindow derived classes under all platforms). + wxTextCtrl under wxGTK (it also works for + wxScrolledWindow derived classes under all platforms). - @sa ScrollPages() + @see ScrollPages() */ virtual bool ScrollLines(int lines); /** - Scrolls the window by the given number of pages down (if @e pages is + Scrolls the window by the given number of pages down (if @a pages is positive) or up. @returns Returns @true if the window was scrolled, @false if it was already - on top/bottom and nothing was done. + on top/bottom and nothing was done. @remarks This function is currently only implemented under MSW and wxGTK. - @sa ScrollLines() + @see ScrollLines() */ virtual bool ScrollPages(int pages); @@ -1794,21 +1713,19 @@ public: Physically scrolls the pixels in the window and move child windows accordingly. @param dx - Amount to scroll horizontally. - + Amount to scroll horizontally. @param dy - Amount to scroll vertically. - + Amount to scroll vertically. @param rect - Rectangle to scroll, if it is @NULL, the whole window is - scrolled (this is always the case under wxGTK which doesn't support this - parameter) + Rectangle to scroll, if it is @NULL, the whole window is + scrolled (this is always the case under wxGTK which doesn't support this + parameter) @remarks Note that you can often use wxScrolledWindow instead of using - this function directly. + this function directly. */ virtual void ScrollWindow(int dx, int dy, - const wxRect* rect = @NULL); + const wxRect* rect = NULL); /** Sets the accelerator table for this window. See wxAcceleratorTable. @@ -1818,7 +1735,6 @@ public: /** Sets the accessible for this window. Any existing accessible for this window will be deleted first, if not identical to @e accessible. - See also wxAccessible. */ void SetAccessible(wxAccessible* accessible); @@ -1829,7 +1745,6 @@ public: happens for the windows usually used to contain children, namely wxPanel and wxTopLevelWindow (and the classes deriving from them). - This method is called implicitly by SetSizer() but if you use SetConstraints() you should call it @@ -1837,31 +1752,30 @@ public: size changes. @param autoLayout - Set this to @true if you wish the Layout function to be - called automatically when the window is resized. + Set this to @true if you wish the Layout function to be + called automatically when the window is resized. - @sa SetConstraints() + @see SetConstraints() */ void SetAutoLayout(bool autoLayout); /** Sets the background colour of the window. - Please see InheritAttributes() for explanation of the difference between this method and SetOwnBackgroundColour(). @param colour - The colour to be used as the background colour, pass - wxNullColour to reset to the default colour. + The colour to be used as the background colour, pass + wxNullColour to reset to the default colour. @remarks The background colour is usually painted by the default - wxEraseEvent event handler function under Windows and - automatically under GTK. + wxEraseEvent event handler function under Windows and + automatically under GTK. - @sa GetBackgroundColour(), SetForegroundColour(), - GetForegroundColour(), ClearBackground(), - Refresh(), wxEraseEvent + @see GetBackgroundColour(), SetForegroundColour(), + GetForegroundColour(), ClearBackground(), + Refresh(), wxEraseEvent */ virtual bool SetBackgroundColour(const wxColour& colour); @@ -1870,8 +1784,8 @@ public: GetBackgroundStyle() for the description of the possible style values. - @sa SetBackgroundColour(), GetForegroundColour(), - SetTransparent() + @see SetBackgroundColour(), GetForegroundColour(), + SetTransparent() */ virtual void SetBackgroundStyle(wxBackgroundStyle style); @@ -1883,14 +1797,14 @@ public: the effect of programmatically calling SetFocus(). - @sa wxFocusEvent, wxPanel::SetFocus, wxPanel::SetFocusIgnoringChildren + @see wxFocusEvent, wxPanel::SetFocus, wxPanel::SetFocusIgnoringChildren */ virtual void SetCanFocus(bool canFocus); /** Sets the caret associated with the window. */ - void SetCaret(wxCaret * caret); + void SetCaret(wxCaret* caret); //@{ /** @@ -1903,13 +1817,11 @@ public: around panel items, for example. @param width - The required client area width. - + The required client area width. @param height - The required client area height. - + The required client area height. @param size - The required client size. + The required client size. */ virtual void SetClientSize(int width, int height); virtual void SetClientSize(const wxSize& size); @@ -1922,14 +1834,14 @@ public: window, it will be deleted. @param constraints - The constraints to set. Pass @NULL to disassociate and delete the window's - constraints. + The constraints to set. Pass @NULL to disassociate and delete the window's + constraints. @remarks You must call SetAutoLayout() to tell a window to use - the constraints automatically in OnSize; otherwise, - you must override OnSize and call Layout() - explicitly. When setting both a wxLayoutConstraints - and a wxSizer, only the sizer will have effect. + the constraints automatically in OnSize; otherwise, you + must override OnSize and call Layout() explicitly. When + setting both a wxLayoutConstraints and a wxSizer, only + the sizer will have effect. */ void SetConstraints(wxLayoutConstraints* constraints); @@ -1943,24 +1855,21 @@ public: /** Sets the window's cursor. Notice that the window cursor also sets it for the children of the window implicitly. - - The @e cursor may be @c wxNullCursor in which case the window cursor will + The @a cursor may be @c wxNullCursor in which case the window cursor will be reset back to default. @param cursor - Specifies the cursor that the window should normally display. + Specifies the cursor that the window should normally display. - @sa ::wxSetCursor, wxCursor + @see ::wxSetCursor, wxCursor */ virtual void SetCursor(const wxCursor& cursor); /** Associates a drop target with this window. - If the window already has a drop target, it is deleted. - @sa GetDropTarget(), @ref overview_wxdndoverview "Drag and drop - overview" + @see GetDropTarget(), @ref overview_wxdndoverview */ void SetDropTarget(wxDropTarget* target); @@ -1968,17 +1877,17 @@ public: Sets the event handler for this window. @param handler - Specifies the handler to be set. + Specifies the handler to be set. @remarks An event handler is an object that is capable of processing the - events sent to a window. By default, the window is - its own event handler, but an application may wish to - substitute another, for example to allow central - implementation of event-handling for a variety of - different window classes. + events sent to a window. By default, the window is its + own event handler, but an application may wish to + substitute another, for example to allow central + implementation of event-handling for a variety of + different window classes. - @sa GetEventHandler(), PushEventHandler(), - PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler + @see GetEventHandler(), PushEventHandler(), + PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler */ void SetEventHandler(wxEvtHandler* handler); @@ -1988,14 +1897,12 @@ public: @b wxWS_EX_VALIDATE_RECURSIVELY - TransferDataTo/FromWindow() and Validate() methods will recursively descend into all children of the window if it has this style flag set. @b wxWS_EX_BLOCK_EVENTS - Normally, the command events are propagated upwards to the window parent recursively until a handler for them is found. Using this style allows to prevent them from being @@ -2005,7 +1912,6 @@ public: @b wxWS_EX_TRANSIENT - This can be used to prevent a window from being used as an implicit parent for the dialogs which were created without a parent. It is useful for the windows which can disappear at @@ -2013,7 +1919,6 @@ public: @b wxWS_EX_CONTEXTHELP - Under Windows, puts a query button on the caption. When pressed, Windows will go into a context-sensitive help mode and wxWidgets will send a wxEVT_HELP event if the user clicked on an @@ -2023,13 +1928,11 @@ public: @b wxWS_EX_PROCESS_IDLE - This window should always process idle events, even if the mode set by wxIdleEvent::SetMode is wxIDLE_PROCESS_SPECIFIED. @b wxWS_EX_PROCESS_UI_UPDATES - This window should always process UI update events, even if the mode set by wxUpdateUIEvent::SetMode is wxUPDATE_UI_PROCESS_SPECIFIED. @@ -2039,8 +1942,8 @@ public: /** This sets the window to receive keyboard input. - @sa HasFocus(), wxFocusEvent, wxPanel::SetFocus, - wxPanel::SetFocusIgnoringChildren + @see HasFocus(), wxFocusEvent, wxPanel::SetFocus, + wxPanel::SetFocusIgnoringChildren */ virtual void SetFocus(); @@ -2058,7 +1961,6 @@ public: use SetOwnFont() instead in this case and see InheritAttributes() for more explanations. - Please notice that the given font is not automatically used for wxPaintDC objects associated with this window, you need to call wxDC::SetFont too. However this font is used by @@ -2066,45 +1968,43 @@ public: GetTextExtent(). @param font - Font to associate with this window, pass - wxNullFont to reset to the default font. + Font to associate with this window, pass + wxNullFont to reset to the default font. @returns @true if the want was really changed, @false if it was already set - to this font and so nothing was done. + to this font and so nothing was done. - @sa GetFont(), InheritAttributes() + @see GetFont(), InheritAttributes() */ bool SetFont(const wxFont& font); /** Sets the foreground colour of the window. - Please see InheritAttributes() for explanation of the difference between this method and SetOwnForegroundColour(). @param colour - The colour to be used as the foreground colour, pass - wxNullColour to reset to the default colour. + The colour to be used as the foreground colour, pass + wxNullColour to reset to the default colour. @remarks The interpretation of foreground colour is open to - interpretation according to the window class; it may - be the text colour or other colour, or it may not be - used at all. + interpretation according to the window class; it may be + the text colour or other colour, or it may not be used + at all. - @sa GetForegroundColour(), SetBackgroundColour(), - GetBackgroundColour(), ShouldInheritColours() + @see GetForegroundColour(), SetBackgroundColour(), + GetBackgroundColour(), ShouldInheritColours() */ virtual void SetForegroundColour(const wxColour& colour); /** Sets the help text to be used as context-sensitive help for this window. - Note that the text is actually stored by the current wxHelpProvider implementation, and not in the window object itself. - @sa GetHelpText(), wxHelpProvider + @see GetHelpText(), wxHelpProvider */ virtual void SetHelpText(const wxString& helpText); @@ -2112,11 +2012,11 @@ public: Sets the identifier of the window. @remarks Each window has an integer identifier. If the application has - not provided one, an identifier will be generated. - Normally, the identifier should be provided on - creation and should not be modified subsequently. + not provided one, an identifier will be generated. + Normally, the identifier should be provided on creation + and should not be modified subsequently. - @sa GetId(), @ref overview_windowids "Window identifiers" + @see GetId(), @ref overview_windowids "Window identifiers" */ void SetId(int id); @@ -2133,11 +2033,10 @@ public: partial size is passed to this function then the sizers will use that size instead of the results of GetBestSize to determine the minimum needs of the window for layout. - Most controls will use this to set their initial size, and their min size to the passed in value (if any.) - @sa SetSize(), GetBestSize(), GetEffectiveMinSize() + @see SetSize(), GetBestSize(), GetEffectiveMinSize() */ void SetInitialSize(const wxSize& size = wxDefaultSize); @@ -2145,9 +2044,9 @@ public: Sets the window's label. @param label - The window label. + The window label. - @sa GetLabel() + @see GetLabel() */ virtual void SetLabel(const wxString& label); @@ -2155,7 +2054,7 @@ public: Sets the maximum client size of the window, to indicate to the sizer layout mechanism that this is the maximum possible size of its client area. - @sa SetMaxSize() + @see SetMaxSize() */ void SetMaxClientSize(const wxSize& size); @@ -2163,7 +2062,7 @@ public: Sets the maximum size of the window, to indicate to the sizer layout mechanism that this is the maximum possible size. - @sa SetMaxClientSize() + @see SetMaxClientSize() */ void SetMaxSize(const wxSize& size); @@ -2173,7 +2072,7 @@ public: area. You may need to call this if you change the window size after construction and before adding to its parent sizer. - @sa SetMinSize() + @see SetMinSize() */ void SetMinClientSize(const wxSize& size); @@ -2183,7 +2082,7 @@ public: if you change the window size after construction and before adding to its parent sizer. - @sa SetMinClientSize() + @see SetMinClientSize() */ void SetMinSize(const wxSize& size); @@ -2191,9 +2090,9 @@ public: Sets the window's name. @param name - A name to set for the window. + A name to set for the window. - @sa GetName() + @see GetName() */ virtual void SetName(const wxString& name); @@ -2201,7 +2100,7 @@ public: Sets the background colour of the window but prevents it from being inherited by the children of this window. - @sa SetBackgroundColour(), InheritAttributes() + @see SetBackgroundColour(), InheritAttributes() */ void SetOwnBackgroundColour(const wxColour& colour); @@ -2209,7 +2108,7 @@ public: Sets the font of the window but prevents it from being inherited by the children of this window. - @sa SetFont(), InheritAttributes() + @see SetFont(), InheritAttributes() */ void SetOwnFont(const wxFont& font); @@ -2217,7 +2116,7 @@ public: Sets the foreground colour of the window but prevents it from being inherited by the children of this window. - @sa SetForegroundColour(), InheritAttributes() + @see SetForegroundColour(), InheritAttributes() */ void SetOwnForegroundColour(const wxColour& colour); @@ -2230,112 +2129,103 @@ public: Sets the position of one of the built-in scrollbars. @param orientation - Determines the scrollbar whose position is to be set. May be wxHORIZONTAL or - wxVERTICAL. - + Determines the scrollbar whose position is to be set. May be wxHORIZONTAL + or wxVERTICAL. @param pos - Position in scroll units. - + Position in scroll units. @param refresh - @true to redraw the scrollbar, @false otherwise. + @true to redraw the scrollbar, @false otherwise. @remarks This function does not directly affect the contents of the - window: it is up to the application to take note of - scrollbar attributes and redraw contents accordingly. + window: it is up to the application to take note of + scrollbar attributes and redraw contents accordingly. - @sa SetScrollbar(), GetScrollPos(), GetScrollThumb(), - wxScrollBar, wxScrolledWindow + @see SetScrollbar(), GetScrollPos(), GetScrollThumb(), + wxScrollBar, wxScrolledWindow */ virtual void SetScrollPos(int orientation, int pos, - bool refresh = @true); + bool refresh = true); /** Sets the scrollbar properties of a built-in scrollbar. @param orientation - Determines the scrollbar whose page size is to be set. May be wxHORIZONTAL or - wxVERTICAL. - + Determines the scrollbar whose page size is to be set. May be wxHORIZONTAL + or wxVERTICAL. @param position - The position of the scrollbar in scroll units. - + The position of the scrollbar in scroll units. @param thumbSize - The size of the thumb, or visible portion of the scrollbar, in scroll units. - + The size of the thumb, or visible portion of the scrollbar, in scroll units. @param range - The maximum position of the scrollbar. - + The maximum position of the scrollbar. @param refresh - @true to redraw the scrollbar, @false otherwise. + @true to redraw the scrollbar, @false otherwise. @remarks Let's say you wish to display 50 lines of text, using the same - font. The window is sized so that you can only see 16 - lines at a time. + font. The window is sized so that you can only see 16 + lines at a time. - @sa @ref overview_scrollingoverview "Scrolling overview", wxScrollBar, - wxScrolledWindow, wxScrollWinEvent + @see @ref overview_scrollingoverview "Scrolling overview", wxScrollBar, + wxScrolledWindow, wxScrollWinEvent */ virtual void SetScrollbar(int orientation, int position, int thumbSize, int range, - bool refresh = @true); + bool refresh = true); //@{ /** Sets the size of the window in pixels. @param x - Required x position in pixels, or wxDefaultCoord to indicate that the existing - value should be used. - + Required x position in pixels, or wxDefaultCoord to indicate that the + existing + value should be used. @param y - Required y position in pixels, or wxDefaultCoord to indicate that the existing - value should be used. - + Required y position in pixels, or wxDefaultCoord to indicate that the + existing + value should be used. @param width - Required width in pixels, or wxDefaultCoord to indicate that the existing - value should be used. - + Required width in pixels, or wxDefaultCoord to indicate that the existing + value should be used. @param height - Required height position in pixels, or wxDefaultCoord to indicate that the + Required height position in pixels, or wxDefaultCoord to indicate that the existing - value should be used. - + value should be used. @param size - wxSize object for setting the size. - + wxSize object for setting the size. @param rect - wxRect object for setting the position and size. - + wxRect object for setting the position and size. @param sizeFlags - Indicates the interpretation of other parameters. It is a bit list of the + Indicates the interpretation of other parameters. It is a bit list of the following: + wxSIZE_AUTO_WIDTH: a wxDefaultCoord width value is taken to indicate + a wxWidgets-supplied default width. - wxSIZE_AUTO_WIDTH: a wxDefaultCoord width value is taken to indicate - a wxWidgets-supplied default width. + wxSIZE_AUTO_HEIGHT: a wxDefaultCoord height value is taken to indicate + a wxWidgets-supplied default height. - wxSIZE_AUTO_HEIGHT: a wxDefaultCoord height value is taken to indicate - a wxWidgets-supplied default height. + wxSIZE_AUTO: wxDefaultCoord size values are taken to indicate + a wxWidgets-supplied default size. - wxSIZE_AUTO: wxDefaultCoord size values are taken to indicate - a wxWidgets-supplied default size. + wxSIZE_USE_EXISTING: existing dimensions should be used + if wxDefaultCoord values are supplied. - wxSIZE_USE_EXISTING: existing dimensions should be used - if wxDefaultCoord values are supplied. - - wxSIZE_ALLOW_MINUS_ONE: allow negative dimensions (i.e. value of + wxSIZE_ALLOW_MINUS_ONE: allow negative dimensions (i.e. value of wxDefaultCoord) to be interpreted - as real dimensions, not default values. - wxSIZE_FORCE: normally, if the position and the size of the window are - already the same as the parameters of this function, nothing is done. but with - this flag a window resize may be forced even in this case (supported in wx - 2.6.2 and later and only implemented for MSW and ignored elsewhere currently) + as real dimensions, not default values. + wxSIZE_FORCE: normally, if the position and the size of the window are + already the same as the parameters of this function, nothing is done. but + with + this flag a window resize may be forced even in this case (supported in wx + 2.6.2 and later and only implemented for MSW and ignored elsewhere + currently) @remarks The second form is a convenience for calling the first form with - default x and y parameters, and must be used with - non-default width and height values. + default x and y parameters, and must be used with + non-default width and height values. - @sa Move() + @see Move() */ virtual void SetSize(int x, int y, int width, int height, int sizeFlags = wxSIZE_AUTO); @@ -2350,7 +2240,7 @@ public: SetMinSize() and SetMaxSize() instead. - @sa wxTopLevelWindow::SetSizeHints. + @see wxTopLevelWindow::SetSizeHints. */ @@ -2359,23 +2249,21 @@ public: will then own the object, and will take care of its deletion. If an existing layout constraints object is already owned by the window, it will be deleted if the deleteOld parameter is @true. - Note that this function will also call SetAutoLayout() implicitly with @true - parameter if the @e sizer is non-@NULL and @false otherwise. + parameter if the @a sizer is non-@NULL and @false otherwise. @param sizer - The sizer to set. Pass @NULL to disassociate and conditionally delete - the window's sizer. See below. - + The sizer to set. Pass @NULL to disassociate and conditionally delete + the window's sizer. See below. @param deleteOld - If @true (the default), this will delete any pre-existing sizer. - Pass @false if you wish to handle deleting the old sizer yourself. + If @true (the default), this will delete any pre-existing sizer. + Pass @false if you wish to handle deleting the old sizer yourself. @remarks SetSizer now enables and disables Layout automatically, but - prior to wxWidgets 2.3.3 the following applied: + prior to wxWidgets 2.3.3 the following applied: */ - void SetSizer(wxSizer* sizer, bool deleteOld=@true); + void SetSizer(wxSizer* sizer, bool deleteOld = true); /** This method calls SetSizer() and then @@ -2384,7 +2272,7 @@ public: size hints which, if this window is a top level one, prevent the user from resizing it to be less than this minimial size. */ - void SetSizerAndFit(wxSizer* sizer, bool deleteOld=@true); + void SetSizerAndFit(wxSizer* sizer, bool deleteOld = true); /** This function tells a window if it should use the system's "theme" code @@ -2393,7 +2281,6 @@ public: obviously needs to support the notion of themes in user defined windows. One such platform is GTK+ where windows can have (very colourful) backgrounds defined by a user's selected theme. - Dialogs, notebook pages and the status bar have this flag set to @true by default so that the default look and feel is simulated best. */ @@ -2402,7 +2289,6 @@ public: //@{ /** Attach a tooltip to the window. - See also: GetToolTip(), wxToolTip */ @@ -2414,8 +2300,7 @@ public: Set the transparency of the window. If the system supports transparent windows, returns @true, otherwise returns @false and the window remains fully opaque. See also CanSetTransparent(). - - The parameter @e alpha is in the range 0..255 where 0 corresponds to a + The parameter @a alpha is in the range 0..255 where 0 corresponds to a fully transparent window and 255 to the fully opaque one. The constants @c wxIMAGE_ALPHA_TRANSPARENT and @c wxIMAGE_ALPHA_OPAQUE can be used. @@ -2444,31 +2329,25 @@ public: will be used. @param minW - Specifies the minimum width allowable. - + Specifies the minimum width allowable. @param minH - Specifies the minimum height allowable. - + Specifies the minimum height allowable. @param maxW - Specifies the maximum width allowable. - + Specifies the maximum width allowable. @param maxH - Specifies the maximum height allowable. - + Specifies the maximum height allowable. @param minSize - Minimum size. - + Minimum size. @param maxSize - Maximum size. + Maximum size. @remarks If this function is called, the user will not be able to size - the virtual area of the window outside the given - bounds. + the virtual area of the window outside the given bounds. */ - virtual void SetVirtualSizeHints(int minW, int minH, int maxW=-1, - int maxH=-1); - void SetVirtualSizeHints(const wxSize& minSize=wxDefaultSize, - const wxSize& maxSize=wxDefaultSize); + virtual void SetVirtualSizeHints(int minW, int minH, int maxW = -1, + int maxH = -1); + void SetVirtualSizeHints(const wxSize& minSize = wxDefaultSize, + const wxSize& maxSize = wxDefaultSize); //@} /** @@ -2481,10 +2360,9 @@ public: after the window creation and that Refresh() might need to be be called after changing the others for the change to take place immediately. - See @ref overview_windowstyles "Window styles" for more information about flags. - @sa GetWindowStyleFlag() + @see GetWindowStyleFlag() */ virtual void SetWindowStyleFlag(long style); @@ -2503,7 +2381,6 @@ public: Return @true from here to allow the colours of this window to be changed by InheritAttributes(), returning @false forbids inheriting them from the parent window. - The base class version returns @false, but this method is overridden in wxControl where it returns @true. */ @@ -2515,57 +2392,47 @@ public: needed if Show() is called immediately after the frame creation. @param show - If @true displays the window. Otherwise, hides it. + If @true displays the window. Otherwise, hides it. @returns @true if the window has been shown or hidden or @false if nothing - was done because it already was in the requested - state. + was done because it already was in the requested state. - @sa IsShown(), Hide(), wxRadioBox::Show + @see IsShown(), Hide(), wxRadioBox::Show */ - virtual bool Show(bool show = @true); + virtual bool Show(bool show = true); /** This function shows a window, like Show(), but using a special visual effect if possible. - - Possible values for @e effect are: - + Possible values for @a effect are: wxSHOW_EFFECT_ROLL - Roll window effect wxSHOW_EFFECT_SLIDE - Sliding window effect wxSHOW_EFFECT_BLEND - Fade in or out effect wxSHOW_EFFECT_EXPAND - Expanding or collapsing effect - For the roll and slide effects the @e dir parameter specifies the animation + For the roll and slide effects the @a dir parameter specifies the animation direction: it can be one of @c wxTOP, @c wxBOTTOM, @c wxLEFT or @c wxRIGHT. For the other effects, this parameter is unused. - - The @e timeout parameter specifies the time of the animation, in + The @a timeout parameter specifies the time of the animation, in milliseconds. If the default value of 0 is used, the default animation time for the current platform is used. - Currently this function is only implemented in wxMSW and does the same thing as Show() in the other ports. - This function is new since wxWidgets version 2.9.0 - @sa HideWithEffect() + @see HideWithEffect() */ virtual bool ShowWithEffect(wxShowEffect effect, unsigned timeout = 0, @@ -2576,22 +2443,21 @@ public: Freeze(). To really thaw the control, it must be called exactly the same number of times as Freeze(). - @sa wxWindowUpdateLocker + @see wxWindowUpdateLocker */ virtual void Thaw(); /** - Turns the given @e flag on if it's currently turned off and vice versa. + Turns the given @a flag on if it's currently turned off and vice versa. This function cannot be used if the value of the flag is 0 (which is often the case for default flags). - Also, please notice that not all styles can be changed after the control creation. @returns Returns @true if the style was turned on by this function, @false - if it was switched off. + if it was switched off. - @sa SetWindowStyleFlag(), HasFlag() + @see SetWindowStyleFlag(), HasFlag() */ bool ToggleWindowStyle(int flag); @@ -2599,24 +2465,22 @@ public: Transfers values from child controls to data areas specified by their validators. Returns @false if a transfer failed. - If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set, the method will also call TransferDataFromWindow() of all child windows. - @sa TransferDataToWindow(), wxValidator, Validate() + @see TransferDataToWindow(), wxValidator, Validate() */ virtual bool TransferDataFromWindow(); /** Transfers values to child controls from data areas specified by their validators. - If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set, the method will also call TransferDataToWindow() of all child windows. @returns Returns @false if a transfer failed. - @sa TransferDataFromWindow(), wxValidator, Validate() + @see TransferDataFromWindow(), wxValidator, Validate() */ virtual bool TransferDataToWindow(); @@ -2624,31 +2488,29 @@ public: Unregisters a system wide hotkey. @param hotkeyId - Numeric identifier of the hotkey. Must be the same id that was passed to + Numeric identifier of the hotkey. Must be the same id that was passed to RegisterHotKey. @returns @true if the hotkey was unregistered successfully, @false if the - id was invalid. + id was invalid. @remarks This function is currently only implemented under MSW. - @sa RegisterHotKey() + @see RegisterHotKey() */ bool UnregisterHotKey(int hotkeyId); /** Unreserve an ID or range of IDs that was reserved by NewControlId(). - See @ref overview_windowidsoverview "Window IDs overview" for more information. @param id - The starting ID of the range of IDs to unreserve. - + The starting ID of the range of IDs to unreserve. @param count - The number of sequential IDs to unreserve. + The number of sequential IDs to unreserve. - @sa NewControlId(), wxIdManager, @ref overview_windowidsoverview - "Window IDs overview" + @see NewControlId(), wxIdManager, @ref overview_windowidsoverview + "Window IDs overview" */ static void UnreserveControlId(wxWindowID id, int count = 1); @@ -2675,8 +2537,8 @@ public: wxUpdateUIEvent::SetUpdateInterval to limit the overhead that wxWidgets incurs by sending update UI events in idle time. + @a flags should be a bitlist of one or more of the following values. - @e flags should be a bitlist of one or more of the following values. If you are calling this function from an OnInternalIdle or OnIdle function, make sure you pass the wxUPDATE_UI_FROMIDLE flag, since this tells the window to only update the UI elements that need @@ -2685,34 +2547,31 @@ public: The following is an example of how to call UpdateWindowUI from an idle function. - @sa wxUpdateUIEvent, DoUpdateWindowUI(), OnInternalIdle() + @see wxUpdateUIEvent, DoUpdateWindowUI(), OnInternalIdle() */ virtual void UpdateWindowUI(long flags = wxUPDATE_UI_NONE); /** Validates the current values of the child controls using their validators. - If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set, the method will also call Validate() of all child windows. @returns Returns @false if any of the validations failed. - @sa TransferDataFromWindow(), TransferDataToWindow(), - wxValidator + @see TransferDataFromWindow(), TransferDataToWindow(), + wxValidator */ virtual bool Validate(); /** Moves the pointer to the given position on the window. - @b NB: This function is not supported under Mac because Apple Human Interface Guidelines forbid moving the mouse cursor programmatically. @param x - The new x position for the cursor. - + The new x position for the cursor. @param y - The new y position for the cursor. + The new y position for the cursor. */ void WarpPointer(int x, int y); }; @@ -2726,23 +2585,23 @@ public: Find the deepest window at the given mouse position in screen coordinates, returning the window if found, or @NULL if not. */ -wxWindow * wxFindWindowAtPoint(const wxPoint& pt); +wxWindow* wxFindWindowAtPoint(const wxPoint& pt); /** Find the deepest window at the mouse pointer position, returning the window and current pointer position in screen coordinates. */ -wxWindow * wxFindWindowAtPointer(wxPoint& pt); +wxWindow* wxFindWindowAtPointer(wxPoint& pt); /** Gets the currently active window (implemented for MSW and GTK only currently, always returns @NULL in the other ports). */ -wxWindow * wxGetActiveWindow(); +wxWindow* wxGetActiveWindow(); /** Returns the first top level parent of the given window, or in other words, the frame or dialog containing it, or @NULL. */ -wxWindow * wxGetTopLevelParent(wxWindow win); +wxWindow* wxGetTopLevelParent(wxWindow win); diff --git a/interface/windowid.h b/interface/windowid.h index c3b82fac44..bd88ca5e90 100644 --- a/interface/windowid.h +++ b/interface/windowid.h @@ -34,7 +34,7 @@ public: need to be unreserved. @param count - The number of sequential IDs to reserve. + The number of sequential IDs to reserve. @returns The value of the first ID in the sequence, or wxID_NONE. */ diff --git a/interface/wizard.h b/interface/wizard.h index bddffa578c..6d9ba969f6 100644 --- a/interface/wizard.h +++ b/interface/wizard.h @@ -37,10 +37,9 @@ public: wizard will resize and reposition the page anyhow. @param parent - The parent wizard - + The parent wizard @param bitmap - The page-specific bitmap if different from the global one + The page-specific bitmap if different from the global one */ wxWizardPage(wxWizard* parent, const wxBitmap& bitmap = wxNullBitmap); @@ -49,10 +48,8 @@ public: This method is called by wxWizard to get the bitmap to display alongside the page. By default, @c m_bitmap member variable which was set in the @ref wxwizardpage() constructor. - If the bitmap was not explicitly set (i.e. if @c wxNullBitmap is returned), the default bitmap for the wizard should be used. - The only cases when you would want to override this function is if the page bitmap depends dynamically on the user choices, i.e. almost never. */ @@ -64,7 +61,7 @@ public: page of the wizard will usually return @NULL from here, but the others will not. - @sa GetPrev() + @see GetPrev() */ wxWizardPage* GetNext(); @@ -74,7 +71,7 @@ public: page of the wizard will usually return @NULL from here, but the others will not. - @sa GetNext() + @see GetNext() */ wxWizardPage* GetPrev(); }; @@ -101,8 +98,8 @@ public: Constructor. It is not normally used by the user code as the objects of this type are constructed by wxWizard. */ - wxWizardEvent(wxEventType type = wxEVT_@NULL, int id = -1, - bool direction = @true); + wxWizardEvent(wxEventType type = wxEVT_NULL, int id = -1, + bool direction = true); /** Return the direction in which the page is changing: for @c @@ -148,14 +145,13 @@ public: SetPrev() or SetNext(). */ - wxWizardPageSimple(wxWizard* parent = @NULL, - wxWizardPage* prev = @NULL, - wxWizardPage* next = @NULL, + wxWizardPageSimple(wxWizard* parent = NULL, + wxWizardPage* prev = NULL, + wxWizardPage* next = NULL, const wxBitmap& bitmap = wxNullBitmap); /** A convenience function to make the pages follow each other. - Example: */ static void Chain(wxWizardPageSimple* first, @@ -221,31 +217,25 @@ public: /** Constructor which really creates the wizard -- if you use this constructor, you shouldn't call Create(). - Notice that unlike almost all other wxWidgets classes, there is no @e size parameter in the wxWizard constructor because the wizard will have a predefined default size by default. If you want to change this, you should use the GetPageAreaSizer() function. @param parent - The parent window, may be @NULL. - + The parent window, may be @NULL. @param id - The id of the dialog, will usually be just -1. - + The id of the dialog, will usually be just -1. @param title - The title of the dialog. - + The title of the dialog. @param bitmap - The default bitmap used in the left side of the wizard. See - also GetBitmap. - + The default bitmap used in the left side of the wizard. See + also GetBitmap. @param pos - The position of the dialog, it will be centered on the screen - by default. - + The position of the dialog, it will be centered on the screen + by default. @param style - Window style is passed to wxDialog. + Window style is passed to wxDialog. */ wxWizard(); wxWizard(wxWindow* parent, int id = -1, @@ -258,31 +248,25 @@ public: /** Creates the wizard dialog. Must be called if the default constructor had been used to create the object. - Notice that unlike almost all other wxWidgets classes, there is no @e size parameter in the wxWizard constructor because the wizard will have a predefined default size by default. If you want to change this, you should use the GetPageAreaSizer() function. @param parent - The parent window, may be @NULL. - + The parent window, may be @NULL. @param id - The id of the dialog, will usually be just -1. - + The id of the dialog, will usually be just -1. @param title - The title of the dialog. - + The title of the dialog. @param bitmap - The default bitmap used in the left side of the wizard. See - also GetBitmap. - + The default bitmap used in the left side of the wizard. See + also GetBitmap. @param pos - The position of the dialog, it will be centered on the screen - by default. - + The position of the dialog, it will be centered on the screen + by default. @param style - Window style is passed to wxDialog. + Window style is passed to wxDialog. */ bool Create(wxWindow* parent, int id = -1, const wxString& title = wxEmptyString, @@ -293,10 +277,8 @@ public: /** This method is obsolete, use GetPageAreaSizer() instead. - Sets the page size to be big enough for all the pages accessible via the given @e firstPage, i.e. this page, its next page and so on. - This method may be called more than once and it will only change the page size if the size required by the new page is bigger than the previously set one. This is useful if the decision about which pages to show is taken during @@ -314,7 +296,6 @@ public: Returns the colour that should be used to fill the area not taken up by the wizard or page bitmap, if a non-zero bitmap placement flag has been set. - See also SetBitmapPlacement(). */ const wxColour GetBitmapBackgroundColour(); @@ -323,7 +304,6 @@ public: Returns the flags indicating how the wizard or page bitmap should be expanded and positioned to fit the page height. By default, placement is 0 (no expansion is done). - See also SetBitmapPlacement() for the possible values. */ int GetBitmapPlacement(); @@ -338,7 +318,6 @@ public: Returns the minimum width for the bitmap that will be constructed to contain the actual wizard or page bitmap if a non-zero bitmap placement flag has been set. - See also SetBitmapPlacement(). */ int GetMinimumBitmapWidth(); @@ -348,7 +327,6 @@ public: the page area sizer is the place-holder for the pages. All pages are resized before being shown to match the wizard page area. - Page area sizer has a minimal size that is the maximum of several values. First, all pages (or other objects) added to the sizer. Second, all pages reachable by repeatedly applying @@ -359,19 +337,16 @@ public: be increased to accommodate the bitmap height. Fifth and finally, wizards are never smaller than some built-in minimal size to avoid wizards that are too small. - The caller can use wxSizer::SetMinSize to enlarge it beyond the minimal size. If @c wxRESIZE_BORDER was passed to constructor, user can resize wizard and consequently the page area (but not make it smaller than the minimal size). - It is recommended to add the first page to the page area sizer. For simple wizards, this will enlarge the wizard to fit the biggest page. For non-linear wizards, the first page of every separate chain should be added. Caller-specified size can be accomplished using wxSizer::SetMinSize. - Adding pages to the page area sizer affects the default border width around page area that can be altered with SetBorder(). */ @@ -388,9 +363,9 @@ public: @ref wxWizardPage::getnext page-GetNext but this could be undesirable if, for example, the pages are created on demand only. - @sa HasPrevPage() + @see HasPrevPage() */ - virtual bool HasNextPage(wxWizardPage * page); + virtual bool HasNextPage(wxWizardPage* page); /** Returns @true if this page is not the last one in the wizard. The base @@ -398,13 +373,13 @@ public: @ref wxWizardPage::getprev page-GetPrev but this could be undesirable if, for example, the pages are created on demand only. - @sa HasNextPage() + @see HasNextPage() */ - virtual bool HasPrevPage(wxWizardPage * page); + virtual bool HasPrevPage(wxWizardPage* page); /** Executes the wizard starting from the given page, returning @true if it was - successfully finished or @false if user cancelled it. The @e firstPage + successfully finished or @false if user cancelled it. The @a firstPage can not be @NULL. */ bool RunWizard(wxWizardPage* firstPage); @@ -418,7 +393,6 @@ public: Sets the colour that should be used to fill the area not taken up by the wizard or page bitmap, if a non-zero bitmap placement flag has been set. - See also SetBitmapPlacement(). */ void SetBitmapBackgroundColour(const wxColour& colour); @@ -426,44 +400,37 @@ public: /** Sets the flags indicating how the wizard or page bitmap should be expanded and positioned to fit the - page height. By default, placement is 0 (no expansion is done). @e placement is + page height. By default, placement is 0 (no expansion is done). @a placement is a bitlist with the following possible values: @b wxWIZARD_VALIGN_TOP - Aligns the bitmap at the top. @b wxWIZARD_VALIGN_CENTRE - Centres the bitmap vertically. @b wxWIZARD_VALIGN_BOTTOM - Aligns the bitmap at the bottom. @b wxWIZARD_HALIGN_LEFT - Left-aligns the bitmap. @b wxWIZARD_HALIGN_CENTRE - Centres the bitmap horizontally. @b wxWIZARD_HALIGN_RIGHT - Right-aligns the bitmap. @b wxWIZARD_TILE - See also SetMinimumBitmapWidth(). */ void SetBitmapPlacement(int placement); @@ -472,7 +439,6 @@ public: Sets width of border around page area. Default is zero. For backward compatibility, if there are no pages in GetPageAreaSizer(), the default is 5 pixels. - If there is a five point border around all controls in a page and the border around page area is left as zero, a five point white space along all dialog borders @@ -488,7 +454,6 @@ public: if a non-zero bitmap placement flag has been set. If this is not set when using bitmap placement, the initial layout may be incorrect. - See also SetBitmapPlacement(). */ void SetMinimumBitmapWidth(int width); @@ -496,11 +461,9 @@ public: /** This method is obsolete, use GetPageAreaSizer() instead. - Sets the minimal size to be made available for the wizard pages. The wizard will take into account the size of the bitmap (if any) itself. Also, the wizard will never be smaller than the default size. - The recommended way to use this function is to lay out all wizard pages using the sizers (even though the wizard is not resizeable) and then use wxSizer::CalcMin in a loop to calculate the maximum diff --git a/interface/wrapsizer.h b/interface/wrapsizer.h index b719d1eaf3..53ed82cfa7 100644 --- a/interface/wrapsizer.h +++ b/interface/wrapsizer.h @@ -28,7 +28,7 @@ class wxWrapSizer : public wxBoxSizer { public: /** - Constructor for a wxWrapSizer. @e orient determines the primary direction of + Constructor for a wxWrapSizer. @a orient determines the primary direction of the sizer (the most common case being @c wxHORIZONTAL). The flags parameter may have the value @c wxEXTEND_LAST_ON_EACH_LINE which will cause the last item on each line to use any remaining space on that line. @@ -39,7 +39,6 @@ public: Not used by an application. This is the mechanism by which sizers can inform sub-items of the first determined size component. The sub-item can then better determine its size requirements. - Returns @true if the information was used (and the sub-item min size was updated). */ diff --git a/interface/wupdlock.h b/interface/wupdlock.h index de935a35e1..ffd5b419fe 100644 --- a/interface/wupdlock.h +++ b/interface/wupdlock.h @@ -43,7 +43,7 @@ public: parameter must be non-@NULL and the window must exist for longer than wxWindowUpdateLocker object itself. */ - wxWindowUpdateLocker(wxWindow * win); + wxWindowUpdateLocker(wxWindow* win); /** Destructor reenables updates for the window this object is associated with. diff --git a/interface/wxcrt.h b/interface/wxcrt.h index 662474ad19..6d3a32a691 100644 --- a/interface/wxcrt.h +++ b/interface/wxcrt.h @@ -7,19 +7,18 @@ ///////////////////////////////////////////////////////////////////////////// /** -Returns a negative value, 0, or positive value if @e p1 is less than, equal +Returns a negative value, 0, or positive value if @a p1 is less than, equal to or greater than @e p2. The comparison is case-sensitive. - This function complements the standard C function @e stricmp() which performs case-insensitive comparison. */ -int wxStrcmp(const char * p1, const char * p2); +int wxStrcmp(const char* p1, const char* p2); /** @b NB: This function is obsolete, use wxString instead. - A macro defined as: + @code #define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0)) @endcode @@ -28,34 +27,31 @@ bool wxStringEq(const wxString& s1, const wxString& s2); /** @b NB: This function is obsolete, use wxString::Find instead. - - Returns @true if the substring @e s1 is found within @e s2, - ignoring case if @e exact is @false. If @e subString is @false, + Returns @true if the substring @a s1 is found within @e s2, + ignoring case if @a exact is @false. If @a subString is @false, no substring matching is done. */ bool wxStringMatch(const wxString& s1, const wxString& s2, - bool subString = @true, - bool exact = @false); + bool subString = true, + bool exact = false); /** This function replaces the dangerous standard function @c sprintf() and is like @c snprintf() available on some platforms. The only difference with sprintf() is that an additional argument - buffer size - is taken and the buffer is never overflowed. - Returns the number of characters copied to the buffer or -1 if there is not enough space. - @sa wxVsnprintf, wxString::Printf + @see wxVsnprintf, wxString::Printf */ -int wxSnprintf(wxChar * buf, size_t len, const wxChar * format, +int wxSnprintf(wxChar* buf, size_t len, const wxChar* format, ...); /** This is a convenience function wrapping wxStringTokenizer which simply returns all tokens - found in the given @e str in an array. - + found in the given @a str in an array. Please see wxStringTokenizer::wxStringTokenizer for the description of the other parameters. @@ -67,14 +63,13 @@ wxArrayString wxStringTokenize(const wxString& str, /** This is a safe version of standard function @e strlen(): it does exactly the same thing (i.e. returns the length of the string) except that it returns 0 if - @e p is the @NULL pointer. + @a p is the @NULL pointer. */ -size_t wxStrlen(const char * p); +size_t wxStrlen(const char* p); /** The same as wxSnprintf but takes a @c va_list argument instead of arbitrary number of parameters. - Note that if @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function supports positional arguments (see wxString::Printf for more information). However other functions of the same family (wxPrintf, wxSprintf, wxFprintf, @@ -83,23 +78,22 @@ size_t wxStrlen(const char * p); parameters even when @c wxUSE_PRINTF_POS_PARAMS is 1. - @sa wxSnprintf, wxString::PrintfV + @see wxSnprintf, wxString::PrintfV */ -int wxVsnprintf(wxChar * buf, size_t len, const wxChar * format, +int wxVsnprintf(wxChar* buf, size_t len, const wxChar* format, va_list argPtr); /** Returns @true if the pointer is either @NULL or points to an empty string, @false otherwise. */ -bool wxIsEmpty(const char * p); +bool wxIsEmpty(const char* p); /** - Returns a negative value, 0, or positive value if @e p1 is less than, equal + Returns a negative value, 0, or positive value if @a p1 is less than, equal to or greater than @e p2. The comparison is case-insensitive. - This function complements the standard C function @e strcmp() which performs case-sensitive comparison. */ -int wxStricmp(const char * p1, const char * p2); +int wxStricmp(const char* p1, const char* p2); diff --git a/interface/xml/xml.h b/interface/xml/xml.h index 46ce11466c..faa4fa12fe 100644 --- a/interface/xml/xml.h +++ b/interface/xml/xml.h @@ -37,8 +37,8 @@ public: wxXmlNode(wxXmlNode* parent, wxXmlNodeType type, const wxString& name, const wxString& content = wxEmptyString, - wxXmlAttribute* attrs = @NULL, - wxXmlNode* next = @NULL, int lineNo = -1); + wxXmlAttribute* attrs = NULL, + wxXmlNode* next = NULL, int lineNo = -1); wxXmlNode(const wxXmlNode& node); wxXmlNode(wxXmlNodeType type, const wxString& name, const wxString& content = wxEmptyString, @@ -61,20 +61,20 @@ public: /** Adds the given node as child of this node. To attach a second children to this node, use the - SetNext() function of the @e child node. + SetNext() function of the @a child node. */ void AddChild(wxXmlNode* child); /** - Removes the first attributes which has the given @e name from the list of + Removes the first attributes which has the given @a name from the list of attributes for this node. */ bool DeleteAttribute(const wxString& name); //@{ /** - Returns the value of the attribute named @e attrName if it does exist. - If it does not exist, the @e defaultVal is returned. + Returns the value of the attribute named @a attrName if it does exist. + If it does not exist, the @a defaultVal is returned. */ bool GetAttribute(const wxString& attrName, wxString* value); wxString GetAttribute(const wxString& attrName, @@ -84,7 +84,7 @@ public: /** Return a pointer to the first attribute of this node. */ - wxXmlAttribute * GetAttributes(); + wxXmlAttribute* GetAttributes(); /** Returns the first child of this node. @@ -103,13 +103,12 @@ public: /** Returns the number of nodes which separe this node from @c grandparent. - This function searches only the parents of this node until it finds @c grandparent or the @NULL node (which is the parent of non-linked nodes or the parent of a wxXmlDocument's root node). */ - int GetDepth(wxXmlNode* grandparent = @NULL); + int GetDepth(wxXmlNode* grandparent = NULL); /** Returns line number of the node in the input XML file or -1 if it is unknown. @@ -134,7 +133,9 @@ public: This function is very useful since the XML snippet @c "tagnametagcontent/tagname" is represented by expat with the following tag tree: + or eventually: + An empty string is returned if the node has no children of type @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE, or if the content of the first child of such types is empty. */ @@ -157,11 +158,11 @@ public: bool HasAttribute(const wxString& attrName); /** - Inserts the @e child node after @e before_node in the children list. - If @e before_node is @NULL, then @e child is prepended to the list of + Inserts the @a child node after @a before_node in the children list. + If @a before_node is @NULL, then @a child is prepended to the list of children and becomes the first child of this node. - Returns @true if @e before_node has been found and the @e child node has been + Returns @true if @a before_node has been found and the @a child node has been inserted. */ bool InsertChild(wxXmlNode* child, wxXmlNode* before_node); @@ -180,7 +181,6 @@ public: Removes the given node from the children list. Returns @true if the node was found and removed or @false if the node could not be found. - Note that the caller is reponsible for deleting the removed node in order to avoid memory leaks. */ @@ -256,12 +256,12 @@ class wxXmlAttribute public: //@{ /** - Creates the attribute with given @e name and @e value. - If @e next is not @NULL, then sets it as sibling of this attribute. + Creates the attribute with given @a name and @e value. + If @a next is not @NULL, then sets it as sibling of this attribute. */ wxXmlAttribute(); wxXmlAttribute(const wxString& name, const wxString& value, - wxXmlAttribute* next = @NULL); + wxXmlAttribute* next = NULL); //@} /** @@ -401,7 +401,6 @@ public: Detaches the document root node and returns it. The document root node will be set to @NULL and thus IsOk() will return @false after calling this function. - Note that the caller is reponsible for deleting the returned node in order to avoid memory leaks. */ @@ -410,14 +409,12 @@ public: /** Returns encoding of in-memory representation of the document (same as passed to Load() or constructor, defaults to UTF-8). - NB: this is meaningless in Unicode build where data are stored as @c wchar_t*. */ wxString GetEncoding(); /** Returns encoding of document (may be empty). - Note: this is the encoding original file was saved in, @b not the encoding of in-memory representation! */ @@ -439,12 +436,11 @@ public: /** Returns @true if the document has been loaded successfully. */ -#define bool IsOk() /* implementation is private */ + bool IsOk(); //@{ /** , @b int@e flags = wxXMLDOC_NONE) - Like above but takes the data from given input stream. */ bool Load(const wxString& filename); diff --git a/interface/xrc/xmlres.h b/interface/xrc/xmlres.h index ce9b0a556c..d6809f76b2 100644 --- a/interface/xrc/xmlres.h +++ b/interface/xrc/xmlres.h @@ -28,17 +28,17 @@ public: Constructor. @param flags - wxXRC_USE_LOCALE: translatable strings will be translated via _(). - wxXRC_NO_SUBCLASSING: subclass property of object nodes will be ignored - (useful for previews in XRC editors). wxXRC_NO_RELOADING will prevent the - XRC files from being reloaded from disk in case they have been modified there - since being last loaded (may slightly speed up loading them). - + wxXRC_USE_LOCALE: translatable strings will be translated via _(). + wxXRC_NO_SUBCLASSING: subclass property of object nodes will be ignored + (useful for previews in XRC editors). wxXRC_NO_RELOADING will prevent the + XRC files from being reloaded from disk in case they have been modified + there + since being last loaded (may slightly speed up loading them). @param domain - The name of the gettext catalog to search for - translatable strings. By default all loaded catalogs will be - searched. This provides a way to allow the strings to only come - from a specific catalog. + The name of the gettext catalog to search for + translatable strings. By default all loaded catalogs will be + searched. This provides a way to allow the strings to only come + from a specific catalog. */ wxXmlResource(const wxString& filemask, int flags = wxXRC_USE_LOCALE, @@ -70,7 +70,7 @@ public: */ bool AttachUnknownControl(const wxString& name, wxWindow* control, - wxWindow* parent = @NULL); + wxWindow* parent = NULL); /** Removes all handlers and deletes them (this means that any handlers added using @@ -88,7 +88,7 @@ public: /** Gets the global resources object or creates one if none exists. */ -#define wxXmlResource* Get() /* implementation is private */ + wxXmlResource* Get(); /** Returns the domain (message catalog) that will be used to load @@ -109,10 +109,10 @@ public: /** Returns a numeric ID that is equivalent to the string ID used in an XML - resource. If an unknown @e str_id is requested (i.e. other than wxID_XXX + resource. If an unknown @a str_id is requested (i.e. other than wxID_XXX or integer), a new record is created which associates the given string with - a number. If @e value_if_not_found is @c wxID_NONE, the number is obtained via - wxNewId. Otherwise @e value_if_not_found is used. + a number. If @a value_if_not_found is @c wxID_NONE, the number is obtained via + wxNewId. Otherwise @a value_if_not_found is used. Macro @c XRCID(name) is provided for convenient use in event tables. */ #define int GetXRCID(const wxString& str_id, int value_if_not_found = -2) /* implementation is private */ @@ -137,12 +137,10 @@ public: //@{ /** - Loads a dialog. @e dlg points to parent window (if any). - + Loads a dialog. @a dlg points to parent window (if any). This form is used to finish creation of an already existing instance (the main reason for this is that you may want to use derived class with a new event table). - Example: */ wxDialog* LoadDialog(wxWindow* parent, const wxString& name); @@ -178,7 +176,6 @@ public: /** Load an object from the resource specifying both the resource name and the class name. - The first overload lets you load nonstandard container windows and returns @c @NULL on failure. The second one lets you finish the creation of an existing @@ -193,7 +190,7 @@ public: //@{ /** - Loads a panel. @e panel points to parent window (if any). This form + Loads a panel. @a panel points to parent window (if any). This form is used to finish creation of an already existing instance. */ wxPanel* LoadPanel(wxWindow* parent, const wxString& name); @@ -210,7 +207,7 @@ public: Sets the global resources object and returns a pointer to the previous one (may be @NULL). */ -#define wxXmlResource* Set(wxXmlResource* res) /* implementation is private */ + wxXmlResource* Set(wxXmlResource* res); /** Sets the domain (message catalog) that will be used to load @@ -226,7 +223,6 @@ public: /** This function unloads a resource previously loaded by Load(). - Returns @true if the resource was successfully unloaded and @false if it hasn't been found in the list of loaded resources. @@ -280,23 +276,23 @@ public: /** Creates children. */ - void CreateChildren(wxObject* parent, bool this_hnd_only = @false); + void CreateChildren(wxObject* parent, bool this_hnd_only = false); /** Helper function. */ void CreateChildrenPrivately(wxObject* parent, - wxXmlNode* rootnode = @NULL); + wxXmlNode* rootnode = NULL); /** Creates a resource from a node. */ wxObject* CreateResFromNode(wxXmlNode* node, wxObject* parent, - wxObject* instance = @NULL); + wxObject* instance = NULL); /** Creates an object (menu, dialog, control, ...) from an XML node. - Should check for validity. @e parent is a higher-level object (usually window, + Should check for validity. @a parent is a higher-level object (usually window, dialog or panel) that is often necessary to create the resource. If @b instance is non-@NULL it should not create a new instance via 'new' but @@ -313,14 +309,12 @@ public: /** ) - Creates a animation from the filename specified in @e param. */ wxAnimation GetAnimation(); /** , @b wxSize@e size = wxDefaultSize) - Gets a bitmap. */ wxBitmap GetBitmap(); @@ -328,7 +322,7 @@ public: /** Gets a bool flag (1, t, yes, on, @true are @true, everything else is @false). */ - bool GetBool(const wxString& param, bool defaultv = @false); + bool GetBool(const wxString& param, bool defaultv = false); /** Gets colour in HTML syntax (#RRGGBB). @@ -348,7 +342,6 @@ public: /** ) - Gets a font. */ wxFont GetFont(); @@ -356,11 +349,10 @@ public: /** Returns the XRCID. */ -#define int GetID() /* implementation is private */ + int GetID(); /** , @b wxSize@e size = wxDefaultSize) - Returns an icon. */ wxIcon GetIcon(); @@ -392,21 +384,18 @@ public: /** ) - Gets the position (may be in dialog units). */ wxPoint GetPosition(); /** ) - Gets the size (may be in dialog units). */ wxSize GetSize(); /** , @b int@e defaults = 0) - Gets style flags from text in form "flag | flag2| flag3 |..." Only understands flags added with AddStyle. */ @@ -414,7 +403,6 @@ public: /** Gets text from param and does some conversions: - replaces \n, \r, \t by respective characters (according to C syntax) replaces @c $ by @c and @c $$ by @c $ (needed for @c _File to @c File translation because of XML syntax) diff --git a/interface/zipstrm.h b/interface/zipstrm.h index 00725371f0..e2ea0877a4 100644 --- a/interface/zipstrm.h +++ b/interface/zipstrm.h @@ -82,15 +82,12 @@ public: The low 8 bits are always the DOS/Windows file attributes for this entry. The values of these attributes are given in the enumeration @c wxZipAttributes. - The remaining bits can store platform specific permission bits or attributes, and their meaning depends on the value of @ref systemmadeby() SetSystemMadeBy. If IsMadeByUnix() is @true then the high 16 bits are unix mode bits. - The following other accessors access these bits: - @ref wxArchiveEntry::isreadonly IsReadOnly/SetIsReadOnly @ref wxArchiveEntry::isdir IsDir/SetIsDir @@ -104,7 +101,6 @@ public: //@{ /** The extra field from the entry's central directory record. - The extra field is used to store platform or application specific data. See Pkware's document 'appnote.txt' for information on its format. */ @@ -116,7 +112,6 @@ public: //@{ /** The extra field from the entry's local record. - The extra field is used to store platform or application specific data. See Pkware's document 'appnote.txt' for information on its format. */ @@ -129,7 +124,6 @@ public: /** The compression method. The enumeration @c wxZipMethod lists the possible values. - The default constructor sets this to wxZIP_METHOD_DEFAULT, which allows wxZipOutputStream to choose the method when writing the entry. @@ -143,10 +137,8 @@ public: Sets the DOS attributes in @ref externalattributes() GetExternalAttributes to be consistent with the @c mode given. - If IsMadeByUnix() is @true then also stores @c mode in GetExternalAttributes(). - Note that the default constructor sets @ref systemmadeby() GetSystemMadeBy to wxZIP_SYSTEM_MSDOS by default. So to be able to store unix @@ -188,12 +180,12 @@ public: to is set to indicate whether the name looks like a directory name (i.e. has a trailing path separator). - @sa @ref overview_wxarcbyname "Looking up an archive entry by name" + @see @ref overview_wxarcbyname "Looking up an archive entry by name" */ wxString GetInternalName(); wxString GetInternalName(const wxString& name, wxPathFormat format = wxPATH_NATIVE, - bool* pIsDir = @NULL); + bool* pIsDir = NULL); //@} /** @@ -207,7 +199,7 @@ public: Indicates that this entry's data is text in an 8-bit encoding. */ bool IsText(); - void SetIsText(bool isText = @true); + void SetIsText(bool isText = true); //@} //@{ @@ -217,12 +209,11 @@ public: this entry, it will then invoke the associated notifier's wxZipNotifier::OnEntryUpdated method. - Setting a notifier is not usually necessary. It is used to handle certain cases when modifying an zip in a pipeline (i.e. between non-seekable streams). - @sa @ref overview_wxarcnoseek "Archives on non-seekable streams", wxZipNotifier + @see @ref overview_wxarcnoseek "Archives on non-seekable streams", wxZipNotifier */ void SetNotifier(wxZipNotifier& notifier); void UnsetNotifier(); @@ -263,7 +254,6 @@ public: //@{ /** Compatibility constructor (requires WXWIN_COMPATIBILITY_2_6). - When this constructor is used, an emulation of seeking is switched on for compatibility with previous versions. Note however, that it is deprecated. @@ -284,7 +274,6 @@ public: /** Returns the zip comment. - This is stored at the end of the zip, therefore when reading a zip from a non-seekable stream, it returns the empty string until the end of the zip has been reached, i.e. when GetNextEntry() returns @@ -308,9 +297,8 @@ public: /** Closes the current entry if one is open, then opens the entry specified - by the @e entry object. - - @e entry should be from the same zip file, and the zip should + by the @a entry object. + @a entry should be from the same zip file, and the zip should be on a seekable stream. */ bool OpenEntry(wxZipEntry& entry); @@ -363,10 +351,8 @@ public: Constructor. @c level is the compression level to use. It can be a value between 0 and 9 or -1 to use the default value which currently is equivalent to 6. - If the parent stream is passed as a pointer then the new filter stream takes ownership of it. If it is passed by reference then it does not. - In a Unicode build the third parameter @c conv is used to translate the filename and comment fields to an 8-bit encoding. It has no effect on the stream's data. @@ -407,11 +393,9 @@ public: Takes ownership of @c entry and uses it to create a new entry in the zip. @c entry is then opened in @c inputStream and its contents copied to this stream. - CopyEntry() is much more efficient than transferring the data using Read() and Write() since it will copy them without decompressing and recompressing them. - For zips on seekable streams, @c entry must be from the same zip file as @c stream. For non-seekable streams, @c entry must also be the last thing read from @c inputStream. @@ -430,11 +414,9 @@ public: /** ) - Create a new directory entry (see wxArchiveEntry::IsDir) with the given name and timestamp. - PutNextEntry() can also be used to create directory entries, by supplying a name with a trailing path separator. @@ -444,7 +426,6 @@ public: //@{ /** , @b off_t@e size = wxInvalidOffset) - Create a new entry with the given name, timestamp and size. */ bool PutNextEntry(wxZipEntry* entry); diff --git a/interface/zstream.h b/interface/zstream.h index 51ecb09385..6b7937c375 100644 --- a/interface/zstream.h +++ b/interface/zstream.h @@ -29,22 +29,18 @@ class wxZlibOutputStream : public wxFilterOutputStream public: //@{ /** - Creates a new write-only compressed stream. @e level means level of + Creates a new write-only compressed stream. @a level means level of compression. It is number between 0 and 9 (including these values) where 0 means no compression and 9 best but slowest compression. -1 is default value (currently equivalent to 6). - If the parent stream is passed as a pointer then the new filter stream takes ownership of it. If it is passed by reference then it does not. - - The @e flags wxZLIB_ZLIB and wxZLIB_GZIP specify whether the output data + The @a flags wxZLIB_ZLIB and wxZLIB_GZIP specify whether the output data will be in zlib or gzip format. wxZLIB_ZLIB is the default. - - If @e flags is wxZLIB_NO_HEADER, then a raw deflate stream is output + If @a flags is wxZLIB_NO_HEADER, then a raw deflate stream is output without either zlib or gzip headers. This is a lower level mode, which is not usually used directly. It can be used to embed a raw deflate stream in a higher level protocol. - The following symbols can be use for the compression level and flags: */ wxZlibOutputStream(wxOutputStream& stream, int level = -1, @@ -85,16 +81,13 @@ public: /** If the parent stream is passed as a pointer then the new filter stream takes ownership of it. If it is passed by reference then it does not. - - The @e flags wxZLIB_ZLIB and wxZLIB_GZIP specify whether the input data + The @a flags wxZLIB_ZLIB and wxZLIB_GZIP specify whether the input data is in zlib or gzip format. If wxZLIB_AUTO is used, then zlib will autodetect the stream type, this is the default. - - If @e flags is wxZLIB_NO_HEADER, then the data is assumed to be a raw + If @a flags is wxZLIB_NO_HEADER, then the data is assumed to be a raw deflate stream without either zlib or gzip headers. This is a lower level mode, which is not usually used directly. It can be used to read a raw deflate stream embedded in a higher level protocol. - This version is not by default compatible with the output produced by the version of @e wxZlibOutputStream in wxWidgets 2.4.x. However, there is a compatibility mode, which is switched on by passing -- 2.45.2