From 4701dc09838c3da46a8bc2836265a7dffee541ee Mon Sep 17 00:00:00 2001 From: Francesco Montorsi Date: Tue, 7 Oct 2008 16:57:34 +0000 Subject: [PATCH] revised st*.h headers git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@56148 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- interface/wx/stackwalk.h | 78 +++---- interface/wx/statbmp.h | 23 +- interface/wx/statbox.h | 14 +- interface/wx/statline.h | 12 +- interface/wx/stattext.h | 48 ++-- interface/wx/statusbr.h | 106 +++------ interface/wx/stc/stc.h | 218 ++++++++++-------- interface/wx/stdpaths.h | 132 +++++------ interface/wx/stopwatch.h | 19 +- interface/wx/strconv.h | 28 +-- interface/wx/stream.h | 7 +- interface/wx/string.h | 471 +++++++++++++++++++++------------------ interface/wx/sysopt.h | 128 +++++++++-- interface/wx/textdlg.h | 2 + 14 files changed, 717 insertions(+), 569 deletions(-) diff --git a/interface/wx/stackwalk.h b/interface/wx/stackwalk.h index 44e6bd7c97..4464d30708 100644 --- a/interface/wx/stackwalk.h +++ b/interface/wx/stackwalk.h @@ -11,36 +11,33 @@ wxStackWalker allows an application to enumerate, or walk, the stack frames (the function callstack). - It is mostly useful in only two situations: - inside wxApp::OnFatalException function to - programmatically get the location of the crash and, in debug builds, in - wxApp::OnAssertFailure to report the caller of the failed - assert. - wxStackWalker works by repeatedly calling - the wxStackWalker::OnStackFrame method for each frame in the - stack, so to use it you must derive your own class from it and override this - method. + It is mostly useful in only two situations: inside wxApp::OnFatalException + function to programmatically get the location of the crash and, in debug builds, + in wxApp::OnAssertFailure to report the caller of the failed assert. + + wxStackWalker works by repeatedly calling the wxStackWalker::OnStackFrame + method for each frame in the stack, so to use it you must derive your own + class from it and override this method. This class will not return anything except raw stack frame addresses if the debug information is not available. Under Win32 this means that the PDB file - matching the program being executed should be present. Note that if you use - Microsoft Visual C++ compiler, you can create PDB files even for the programs - built in release mode and it doesn't affect the program size (at least if you - don't forget to add @c /opt:ref option which is suppressed by using - @c /debug linker option by default but should be always enabled for - release builds). Under Unix, you need to compile your program with debugging - information (usually using @c -g compiler and linker options) to get the - file and line numbers information, however function names should be available - even without it. Of course, all this is only @true if you build using a recent - enough version of GNU libc which provides the @c backtrace() function - needed to walk the stack. - - @ref overview_debuggingoverview "debugging overview" for how to make it - available. + matching the program being executed should be present. + Note that if you use Microsoft Visual C++ compiler, you can create PDB files + even for the programs built in release mode and it doesn't affect the program + size (at least if you don't forget to add @c /opt:ref option which is suppressed + by using @c /debug linker option by default but should be always enabled for + release builds). + Under Unix, you need to compile your program with debugging information + (usually using @c -g compiler and linker options) to get the file and line + numbers information, however function names should be available even without it. + Of course, all this is only @true if you build using a recent enough version + of GNU libc which provides the @c backtrace() function needed to walk the stack. + + See @ref overview_debugging for how to make it available. @library{wxbase} - @category{FIXME} + @category{debugging} @see wxStackFrame */ @@ -48,8 +45,7 @@ class wxStackWalker { public: /** - Constructor does nothing, use Walk() to walk the - stack. + Constructor does nothing, use Walk() to walk the stack. */ wxStackWalker(); @@ -69,14 +65,15 @@ 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 @a maxDepth frames are walked from the innermost to the outermost one. */ virtual void Walk(size_t skip = 1, size_t maxDepth = 200); /** Enumerate stack frames from the location of uncaught exception. - This method can only be called from - wxApp::OnFatalException. + This method can only be called from wxApp::OnFatalException(). + Up to @a maxDepth frames are walked from the innermost to the outermost one. */ virtual void WalkFromException(size_t maxDepth = 200); @@ -88,12 +85,11 @@ public: @class wxStackFrame wxStackFrame represents a single stack frame, or a single function in the call - stack, and is used exclusively together with - wxStackWalker, see there for a more detailed - discussion. + stack, and is used exclusively together with wxStackWalker, see there for a more + detailed discussion. @library{wxbase} - @category{FIXME} + @category{debugging} @see wxStackWalker */ @@ -106,10 +102,10 @@ public: void* GetAddress() const; /** - 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. + 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. */ wxString GetFileName() const; @@ -131,8 +127,7 @@ public: wxString GetModule() const; /** - Return the unmangled (if possible) name of the function containing this - frame. + Return the unmangled (if possible) name of the function containing this frame. */ wxString GetName() const; @@ -143,11 +138,10 @@ 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. + 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. + This function currently is only implemented under Win32 and requires a PDB file. */ bool GetParam(size_t n, wxString* type, wxString* name, wxString* value) const; diff --git a/interface/wx/statbmp.h b/interface/wx/statbmp.h index 58bd010c74..8fe3981cf9 100644 --- a/interface/wx/statbmp.h +++ b/interface/wx/statbmp.h @@ -9,12 +9,13 @@ /** @class wxStaticBitmap - A static bitmap control displays a bitmap. Native implementations on some - platforms are only meant for display of the small icons in the dialog + A static bitmap control displays a bitmap. Native implementations on some + platforms are only meant for display of the small icons in the dialog boxes. In particular, under Windows 9x the size of bitmap is limited to 64*64 pixels. - If you want to display larger images portably, you may use generic - implementation wxGenericStaticBitmap declared in . + + If you want to display larger images portably, you may use generic + implementation wxGenericStaticBitmap declared in \. @library{wxcore} @category{ctrl} @@ -29,7 +30,7 @@ public: Default constructor */ wxStaticBitmap(); - + /** Constructor, creating and showing a static bitmap control. @@ -68,18 +69,18 @@ public: const wxString& name = "staticBitmap"); /** - Returns the bitmap currently used in the control. Notice that this method can - be called even if SetIcon() had been used. + Returns the bitmap currently used in the control. + Notice that this method can be called even if SetIcon() had been used. @see SetBitmap() */ virtual wxBitmap GetBitmap() const; /** - Returns the icon currently used in the control. Notice that this method can - only be called if SetIcon() had been used: an icon - can't be retrieved from the control if a bitmap had been set (using - wxStaticBitmap::SetBitmap). + Returns the icon currently used in the control. + Notice that this method can only be called if SetIcon() had been used: an icon + can't be retrieved from the control if a bitmap had been set + (using wxStaticBitmap::SetBitmap). @see SetIcon() */ diff --git a/interface/wx/statbox.h b/interface/wx/statbox.h index c612133138..7fa19dc21a 100644 --- a/interface/wx/statbox.h +++ b/interface/wx/statbox.h @@ -35,7 +35,7 @@ public: Default constructor */ wxStaticBox(); - + /** Constructor, creating and showing a static box. @@ -46,11 +46,11 @@ public: @param 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 wxDefaultSize is specified then a default size is chosen. @param style Window style. See wxStaticBox. @param name @@ -71,8 +71,8 @@ public: virtual ~wxStaticBox(); /** - Creates the static box for two-step construction. See wxStaticBox() - for further details. + Creates the static box for two-step construction. + See wxStaticBox() for further details. */ bool Create(wxWindow* parent, wxWindowID id, const wxString& label, diff --git a/interface/wx/statline.h b/interface/wx/statline.h index 1c8069ebdd..745e1aeb21 100644 --- a/interface/wx/statline.h +++ b/interface/wx/statline.h @@ -25,7 +25,7 @@ @endStyleTable @library{wxcore} - @category{FIXME} + @category{ctrl} @see wxStaticBox */ @@ -36,7 +36,7 @@ public: Default constructor */ wxStaticLine(); - + /** Constructor, creating and showing a static line. @@ -45,8 +45,8 @@ public: @param id 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. @@ -64,8 +64,8 @@ public: const wxString& name = "staticLine"); /** - Creates the static line for two-step construction. See wxStaticLine() - for further details. + Creates the static line for two-step construction. + See wxStaticLine() for further details. */ bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, const wxPoint& pos = wxDefaultPosition, diff --git a/interface/wx/stattext.h b/interface/wx/stattext.h index 686ecaf4d4..456c0dc285 100644 --- a/interface/wx/stattext.h +++ b/interface/wx/stattext.h @@ -50,7 +50,7 @@ public: Default constructor. */ wxStaticText(); - + /** Constructor, creating and showing a text control. @@ -90,32 +90,33 @@ public: /** Returns the contents of the control. - Note that the returned string contains both the mnemonics (@c characters), + + Note that the returned string contains both the mnemonics (@& characters), if any, and markup tags, if any. - Use GetLabelText() if only the - label text is needed. + Use GetLabelText() if only the label text is needed. */ wxString GetLabel() const; - //@{ /** - 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 @a label string without the - mnemonics - characters (if any) and without the markup. + This method returns the control's label without the mnemonics characters + (if any) and without the markup (if the control has @c wxST_MARKUP style). + */ + wxString GetLabelText() const; + + /** + This overload returns the given @a label string without the + mnemonics characters (if any) and without the markup. */ - wxString GetLabelText(); - const static wxString GetLabelText(const wxString& label); - //@} + static wxString GetLabelText(const wxString& label); /** 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: @@ -156,14 +157,16 @@ public: - +
<span>generic formatter tag; see Pango Markup for more information.generic formatter tag; see Pango Markup + (http://library.gnome.org/devel/pango/unstable/PangoMarkupFormat.html) + 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. + closed) otherwise it can be not shown correctly or at all. Also note that you need to escape the following special characters: + @@ -190,23 +193,24 @@ public:
@b Special character@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 - described above. + 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 @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. Note that this width is not + boundaries so it might not be the case if words are too long). + + If @a width is negative, no wrapping is done. Note that this width is not necessarily the total width of the control, since a few pixels for the border (depending on the controls border style) may be added. diff --git a/interface/wx/statusbr.h b/interface/wx/statusbr.h index 196e9e28eb..ea9c25058a 100644 --- a/interface/wx/statusbr.h +++ b/interface/wx/statusbr.h @@ -10,55 +10,53 @@ @class wxStatusBar A status bar is a narrow window that can be placed along the bottom of a frame - to give - small amounts of status information. It can contain one or more fields, one or - more of which can - be variable length according to the size of the window. - - wxWindow - - wxEvtHandler - - wxObject + to give small amounts of status information. It can contain one or more fields, + one or more of which can be variable length according to the size of the window. @beginStyleTable @style{wxST_SIZEGRIP} - On Windows 95, displays a gripper at right-hand side of the status - bar. + On Windows 95, displays a gripper at right-hand side of the status bar. @endStyleTable + @todo reference to win95 may be old and wrong + + @remarks + It is possible to create controls and other windows on the status bar. + Position these windows from an OnSize event handler. + @library{wxcore} @category{miscwnd} - @see wxFrame, @ref overview_samplestatbar "Status bar sample" + @see wxFrame, @ref page_samples_statbar */ class wxStatusBar : public wxWindow { public: - //@{ + /** + Default ctor. + */ + wxStatusBar(); + /** Constructor, creating the window. @param parent 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. @param name 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 + item, allowing the application user to set Motif resource values for individual windows. @see Create() */ - wxStatusBar(); wxStatusBar(wxWindow* parent, wxWindowID id = wxID_ANY, long style = wxST_SIZEGRIP, const wxString& name = "statusBar"); - //@} /** Destructor. @@ -99,7 +97,7 @@ public: The number of the status field to retrieve, starting from zero. @return The status field string if the field is valid, otherwise the - empty string. + empty string. @see SetStatusText() */ @@ -126,64 +124,31 @@ public: The number of fields. @param widths An array of n integers interpreted in the same way as - in SetStatusWidths + in SetStatusWidths(). */ virtual void SetFieldsCount(int number = 1, int* widths = NULL); /** - Sets the minimal possible height for the status bar. The real height may be - bigger than the height specified here depending on the size of the font used by - the status bar. + Sets the minimal possible height for the status bar. + + The real height may be bigger than the height specified here depending + on the size of the font used by the status bar. */ virtual void SetMinHeight(int height); /** Sets the styles of the fields in the status line which can make fields appear - flat - or raised instead of the standard sunken 3D border. + flat 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. + 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: - - - - - - - - wxSB_NORMAL - - - - - (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 - - - - - A raised 3D border is painted around the field. + - wxSB_NORMAL (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: A raised 3D border is painted around the field. */ virtual void SetStatusStyles(int n, int* styles); @@ -207,25 +172,24 @@ 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. + 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 + 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. + non-variable fields, divided by the number of variable fields. - @see SetFieldsCount(), wxFrame::SetStatusWidths + @see SetFieldsCount(), wxFrame::SetStatusWidths() */ virtual void SetStatusWidths(int n, int* widths); }; diff --git a/interface/wx/stc/stc.h b/interface/wx/stc/stc.h index f247fc338f..38cb6b0eab 100644 --- a/interface/wx/stc/stc.h +++ b/interface/wx/stc/stc.h @@ -11,239 +11,234 @@ The type of events sent from wxStyledTextCtrl. - TODO + @todo list styled text ctrl events. @library{wxbase} - @category{FIXME} + @category{events} */ class wxStyledTextEvent : public wxCommandEvent { public: //@{ /** - + Ctors; used internally by wxWidgets. */ wxStyledTextEvent(wxEventType commandType = 0, int id = 0); wxStyledTextEvent(const wxStyledTextEvent& event); //@} /** - - */ - wxEvent* Clone() const; - /** - */ bool GetAlt() const; /** - + */ bool GetControl() const; /** - + */ bool GetDragAllowMove(); /** - + */ wxDragResult GetDragResult(); /** - + */ wxString GetDragText(); /** - + */ int GetFoldLevelNow() const; /** - + */ int GetFoldLevelPrev() const; /** - + */ int GetKey() const; /** - + */ int GetLParam() const; /** - + */ int GetLength() const; /** - + */ int GetLine() const; /** - + */ int GetLinesAdded() const; /** - + */ int GetListType() const; /** - + */ int GetMargin() const; /** - + */ int GetMessage() const; /** - + */ int GetModificationType() const; /** - + */ int GetModifiers() const; /** - + */ int GetPosition() const; /** - + */ bool GetShift() const; /** - + */ wxString GetText() const; /** - + */ int GetWParam() const; /** - + */ int GetX() const; /** - + */ int GetY() const; /** - + */ void SetDragAllowMove(bool val); /** - + */ void SetDragResult(wxDragResult val); /** - + */ void SetDragText(const wxString& val); /** - + */ void SetFoldLevelNow(int val); /** - + */ void SetFoldLevelPrev(int val); /** - + */ void SetKey(int k); /** - + */ void SetLParam(int val); /** - + */ void SetLength(int len); /** - + */ void SetLine(int val); /** - + */ void SetLinesAdded(int num); /** - + */ void SetListType(int val); /** - + */ void SetMargin(int val); /** - + */ void SetMessage(int val); /** - + */ void SetModificationType(int t); /** - + */ void SetModifiers(int m); /** - + */ void SetPosition(int pos); /** - + */ void SetText(const wxString& t); /** - + */ void SetWParam(int val); /** - + */ void SetX(int val); /** - + */ void SetY(int val); }; @@ -256,19 +251,72 @@ public: A wxWidgets implementation of the Scintilla source code editing component. As well as features found in standard text editing components, Scintilla - includes - features especially useful when editing and debugging source code. These - include - support for syntax styling, error indicators, code completion and call tips. - The - selection margin can contain markers like those used in debuggers to indicate + includes features especially useful when editing and debugging source code. + These include support for syntax styling, error indicators, code completion + and call tips. + + The selection margin can contain markers like those used in debuggers to indicate breakpoints and the current line. Styling choices are more open than with many editors, allowing the use of proportional fonts, bold and italics, multiple foreground and background colours and multiple fonts. wxStyledTextCtrl is a 1 to 1 mapping of "raw" scintilla interface, whose - documentation - can be found in the Scintilla website. + documentation can be found in the Scintilla website (http://www.scintilla.org/). + + @beginEventTable{wxStyledTextEvent} + @event{EVT_STC_CHANGE(id, fn)} + TOWRITE + @event{EVT_STC_STYLENEEDED(id, fn)} + TOWRITE + @event{EVT_STC_CHARADDED(id, fn)} + TOWRITE + @event{EVT_STC_SAVEPOINTREACHED(id, fn)} + TOWRITE + @event{EVT_STC_SAVEPOINTLEFT(id, fn)} + TOWRITE + @event{EVT_STC_ROMODIFYATTEMPT(id, fn)} + TOWRITE + @event{EVT_STC_KEY(id, fn)} + TOWRITE + @event{EVT_STC_DOUBLECLICK(id, fn)} + TOWRITE + @event{EVT_STC_UPDATEUI(id, fn)} + TOWRITE + @event{EVT_STC_MODIFIED(id, fn)} + TOWRITE + @event{EVT_STC_MACRORECORD(id, fn)} + TOWRITE + @event{EVT_STC_MARGINCLICK(id, fn)} + TOWRITE + @event{EVT_STC_NEEDSHOWN(id, fn)} + TOWRITE + @event{EVT_STC_PAINTED(id, fn)} + TOWRITE + @event{EVT_STC_USERLISTSELECTION(id, fn)} + TOWRITE + @event{EVT_STC_URIDROPPED(id, fn)} + TOWRITE + @event{EVT_STC_DWELLSTART(id, fn)} + TOWRITE + @event{EVT_STC_DWELLEND(id, fn)} + TOWRITE + @event{EVT_STC_START_DRAG(id, fn)} + TOWRITE + @event{EVT_STC_DRAG_OVER(id, fn)} + TOWRITE + @event{EVT_STC_DO_DROP(id, fn)} + TOWRITE + @event{EVT_STC_ZOOM(id, fn)} + TOWRITE + @event{EVT_STC_HOTSPOT_CLICK(id, fn)} + TOWRITE + @event{EVT_STC_HOTSPOT_DCLICK(id, fn)} + TOWRITE + @event{EVT_STC_CALLTIP_CLICK(id, fn)} + TOWRITE + @event{EVT_STC_AUTOCOMP_SELECTION(id, fn)} + TOWRITE + @endEventTable @library{wxbase} @category{stc} @@ -299,9 +347,6 @@ public: void AddStyledText(const wxMemoryBuffer& data); /** - BEGIN generated section. The following code is automatically generated - by gen_iface.py. Do not edit this file. Edit stc.h.in instead - and regenerate Add text to the document at current position. */ void AddText(const wxString& text); @@ -461,8 +506,7 @@ public: void AutoCompSetSeparator(int separatorCharacter); /** - Change the type-separator character in the string setting up an auto-completion - list. + Change the type-separator character in the string setting up an auto-completion list. Default is '?' but can be changed if items contain '?'. */ void AutoCompSetTypeSeparator(int separatorCharacter); @@ -673,7 +717,7 @@ public: void CopyText(int length, const wxString& text); /** - + */ bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, const wxPoint& pos = wxDefaultPosition, @@ -888,12 +932,12 @@ public: int GetControlCharSymbol() const; /** - + */ wxString GetCurLine(int* OUTPUT); /** - + */ wxCharBuffer GetCurLineRaw(int* OUTPUT); @@ -1195,7 +1239,7 @@ public: wxCharBuffer GetSelectedTextRaw(); /** - + */ void GetSelection(int* OUTPUT, int* OUTPUT); @@ -1346,7 +1390,7 @@ public: int GetWrapVisualFlagsLocation() const; /** - + */ int GetXOffset() const; @@ -1407,13 +1451,12 @@ public: except they behave differently when word-wrap is enabled: They go first to the start / end of the display line, like (Home|LineEnd)Display The difference is that, the cursor is already at the point, it goes on to the - start - or end of the document line, as appropriate for (Home|LineEnd|VCHome)(Extend)?. + start or end of the document line, as appropriate for (Home|LineEnd|VCHome)(Extend)?. */ void HomeWrap(); /** - + */ void HomeWrapExtend(); @@ -1510,12 +1553,12 @@ public: void LineEndRectExtend(); /** - + */ void LineEndWrap(); /** - + */ void LineEndWrapExtend(); @@ -1710,17 +1753,17 @@ public: void ParaDown(); /** - + */ void ParaDownExtend(); /** - + */ void ParaUp(); /** - + */ void ParaUpExtend(); @@ -1790,17 +1833,14 @@ public: int ReplaceTarget(const wxString& text); /** - Replace the target text with the argument text after - d processing. + Replace the target text with the argument text after d processing. Text is counted so it can contain NULs. - Looks for - d where d is between 1 and 9 and replaces these with the strings - matched in the last search operation which were surrounded by - ( and - ). + + Looks for d where d is between 1 and 9 and replaces these with the strings + matched in the last search operation which were surrounded by ( and ). + Returns the length of the replacement text including any change - caused by processing the - d patterns. + caused by processing the d patterns. */ int ReplaceTargetRE(const wxString& text); @@ -1995,7 +2035,7 @@ public: void SetFoldMarginColour(bool useSetting, const wxColour& back); /** - + */ void SetFoldMarginHiColour(bool useSetting, const wxColour& fore); @@ -2048,7 +2088,7 @@ public: void SetKeyWords(int keywordSet, const wxString& keyWords); /** - + */ void SetLastKeydownProcessed(bool val); @@ -2638,12 +2678,12 @@ public: void VCHomeRectExtend(); /** - + */ void VCHomeWrap(); /** - + */ void VCHomeWrapExtend(); diff --git a/interface/wx/stdpaths.h b/interface/wx/stdpaths.h index a76ca33f08..ee4c21030e 100644 --- a/interface/wx/stdpaths.h +++ b/interface/wx/stdpaths.h @@ -16,17 +16,16 @@ for the Unix, Windows and Mac OS X systems, however please note that these are just the examples and the actual values may differ. For example, under Windows: the system administrator may change the standard directories locations, i.e. - the Windows directory may be named @c W:\\Win2003 instead of - the default @c C:\\Windows. + the Windows directory may be named @c "W:\Win2003" instead of + the default @c "C:\Windows". - The strings @c appname and @c username should be - replaced with the value returned by wxApp::GetAppName - and the name of the currently logged in user, respectively. The string - @c prefix is only used under Unix and is @c /usr/local by + The strings @c appname and @c username should be replaced with the value + returned by wxApp::GetAppName() and the name of the currently logged in user, + respectively. The string @c prefix is only used under Unix and is @c /usr/local by default but may be changed using wxStandardPaths::SetInstallPrefix. - The directories returned by the methods of this class may or may not exist. If - they don't exist, it's up to the caller to create them, wxStandardPaths doesn't + The directories returned by the methods of this class may or may not exist. + If they don't exist, it's up to the caller to create them, wxStandardPaths doesn't do it. Finally note that these functions only work with standardly packaged @@ -37,15 +36,15 @@ This class is MT-safe: its methods may be called concurrently from different threads without additional locking. - Note that you don't allocate an instance of class wxStandardPaths, but retrieve the - global standard paths object using @c wxStandardPaths::Get on which you call the + Note that you don't allocate an instance of class wxStandardPaths, but retrieve the + global standard paths object using @c wxStandardPaths::Get on which you call the desired methods. @library{wxbase} @category{file} @see wxFileConfig - */ +*/ class wxStandardPaths { public: @@ -57,9 +56,9 @@ public: /** Return the directory containing the system config files. Example return values: - - Unix: @c /etc - - Windows: @c C:\\Documents @c and @c Settings\\All @c Users\\Application Data - - Mac: @c /Library/Preferences + - Unix: @c /etc + - Windows: @c "C:\Documents and Settings\All Users\Application Data" + - Mac: @c /Library/Preferences @see wxFileConfig */ @@ -69,9 +68,9 @@ public: Return the location of the applications global, i.e. not user-specific, data files. Example return values: - - Unix: @c prefix/share/appname - - Windows: the directory where the executable file is located - - Mac: @c appname.app/Contents/SharedSupport bundle subdirectory + - Unix: @c prefix/share/appname + - Windows: the directory where the executable file is located + - Mac: @c appname.app/Contents/SharedSupport bundle subdirectory @see GetLocalDataDir() */ @@ -80,9 +79,9 @@ public: /** Return the directory containing the current user's documents. Example return values: - - Unix: @c ~ (the home directory) - - Windows: @c C:\\Documents @c and @c Settings\\username\\My Documents - - Mac: @c ~/Documents + - Unix: @c ~ (the home directory) + - Windows: @c "C:\Documents and Settings\username\My Documents" + - Mac: @c ~/Documents @since 2.7.0 */ @@ -91,36 +90,38 @@ public: /** 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 + - Unix: @c /usr/local/bin/exename + - Windows: @c "C:\Programs\AppFolder\exename.exe" + - Mac: @c /Programs/exename */ virtual wxString GetExecutablePath() const; /** - @note This function is only available under Unix. - Return the program installation prefix, e.g. @c /usr, @c /opt or - @c /home/zeitlin. + 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 - now) and finally returns the default @c /usr/local value if it failed. + value, otherwise tries to determine it automatically (Linux only right now) + and finally returns the default @c /usr/local value if it failed. + + @note This function is only available under Unix. */ wxString GetInstallPrefix() const; /** 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/appname. + + This is the same as GetDataDir() except under Unix where it returns @c /etc/appname. */ virtual wxString GetLocalDataDir() const; /** 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 @a lang subdirectory of - GetResourcesDir() (or @c lang.lproj under Mac OS X) but is something quite - different for message catalog category under Unix where it returns the standard + + In general this is just the same as @a lang subdirectory of GetResourcesDir() + (or @c lang.lproj under Mac OS X) but is something quite different for + message catalog category under Unix where it returns the standard @c prefix/share/locale/lang/LC_MESSAGES directory. @since 2.7.0 @@ -131,24 +132,25 @@ public: /** Return the directory where the loadable modules (plugins) live. Example return values: - - Unix: @c prefix/lib/appname - - Windows: the directory of the executable file - - Mac: @c appname.app/Contents/PlugIns bundle subdirectory + - Unix: @c prefix/lib/appname + - Windows: the directory of the executable file + - Mac: @c appname.app/Contents/PlugIns bundle subdirectory @see wxDynamicLibrary */ virtual wxString GetPluginsDir() const; /** - 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. + 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 prefix/share/@e appname - - Windows: the directory where the executable file is located - - Mac: @c appname.app/Contents/Resources bundle subdirectory + - Unix: @c prefix/share/appname + - Windows: the directory where the executable file is located + - Mac: @c appname.app/Contents/Resources bundle subdirectory @since 2.7.0 @@ -157,10 +159,9 @@ public: virtual wxString GetResourcesDir() const; /** - Return the directory for storing temporary files. To create unique temporary - files, - it is best to use wxFileName::CreateTempFileName for correct behaviour when - multiple processes are attempting to create temporary files. + Return the directory for storing temporary files. + To create unique temporary files, it is best to use wxFileName::CreateTempFileName + for correct behaviour when multiple processes are attempting to create temporary files. @since 2.7.2 */ @@ -168,40 +169,42 @@ public: /** Return the directory for the user config files: - - Unix: @c ~ (the home directory) - - Windows: @c C:\\Documents @c and @c Settings\\username\\Application Data - - Mac: @c ~/Library/Preferences + - Unix: @c ~ (the home directory) + - Windows: @c "C:\Documents and Settings\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. + directory, otherwise GetUserDataDir() is more appropriate. */ virtual wxString GetUserConfigDir() const; /** Return the directory for the user-dependent application data files: - - Unix: @c ~/.appname - - Windows: @c C:\\Documents @c and @c Settings\\username\\Application @c Data\\appname - - Mac: @c ~/Library/Application @c Support/appname + - Unix: @c ~/.appname + - Windows: @c "C:\Documents and Settings\username\Application Data\appname" + - Mac: @c "~/Library/Application Support/appname" */ virtual wxString GetUserDataDir() const; /** 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 @c and @c Settings\\username\\Local @c Settings\\Application @c Data\\appname + @c "C:\Documents and Settings\username\Local Settings\Application Data\appname" */ virtual wxString GetUserLocalDataDir() const; /** - @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. + 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 to pass its value defined in @c config.h to this function. + + @note This function is only available under Unix. */ void SetInstallPrefix(const wxString& prefix); @@ -209,10 +212,11 @@ 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 @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. + + 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/wx/stopwatch.h b/interface/wx/stopwatch.h index bd06d1d38b..d36dd50f8c 100644 --- a/interface/wx/stopwatch.h +++ b/interface/wx/stopwatch.h @@ -9,11 +9,12 @@ /** @class wxStopWatch - The wxStopWatch class allow you to measure time intervals. For example, you may - use it to measure the time elapsed by some function: + The wxStopWatch class allow you to measure time intervals. + + For example, you may use it to measure the time elapsed by some function: @code - wxStopWatch sw; + wxStopWatch sw; CallLongRunningFunction(); wxLogMessage("The long running function took %ldms to execute", sw.Time()); @@ -38,8 +39,8 @@ public: wxStopWatch(); /** - Pauses the stop watch. Call Resume() to resume - time measuring again. + 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. @@ -47,8 +48,7 @@ public: void Pause(); /** - Resumes the stop watch which had been paused with - Pause(). + Resumes the stop watch which had been paused with Pause(). */ void Resume(); @@ -58,9 +58,8 @@ public: void Start(long milliseconds = 0); /** - Returns the time in milliseconds since the start (or restart) or the last call - of - Pause(). + Returns the time in milliseconds since the start (or restart) or the last + call of Pause(). */ long Time() const; }; diff --git a/interface/wx/strconv.h b/interface/wx/strconv.h index 6769233f16..a234e7e06d 100644 --- a/interface/wx/strconv.h +++ b/interface/wx/strconv.h @@ -30,7 +30,7 @@ @library{wxbase} @category{conv} - @see wxCSConv, wxEncodingConverter, @ref overview_mbconv "wxMBConv classes overview" + @see wxCSConv, wxEncodingConverter, @ref overview_mbconv */ class wxMBConv { @@ -116,10 +116,11 @@ public: @a dst is non-@NULL, unused otherwise. @param src Point to the source string, must not be @NULL. - @param - The number of characters of the source string to convert or @c - wxNO_LEN (default parameter) to convert everything up to and + @param srcLen + The number of characters of the source string to convert or + @c wxNO_LEN (default parameter) to convert everything up to and including the terminating @c NUL character(s). + @return The number of character written (or which would have been written if it were non-@NULL) to @a dst or @c wxCONV_FAILED on error. @@ -143,10 +144,11 @@ public: @a dst is non-@NULL, unused otherwise. @param src Point to the source string, must not be @NULL. - @param - The number of characters of the source string to convert or @c - wxNO_LEN (default parameter) to convert everything up to and + @param srcLen + The number of characters of the source string to convert or + @c wxNO_LEN (default parameter) to convert everything up to and including the terminating @c NUL character. + @return The number of character written (or which would have been written if it were non-@NULL) to @a dst or @c wxCONV_FAILED on error. @@ -301,7 +303,7 @@ public: @library{wxbase} @category{conv} - @see wxMBConvUTF8, @ref overview_mbconv "wxMBConv classes overview" + @see wxMBConvUTF8, @ref overview_mbconv */ class wxMBConvUTF7 : public wxMBConv { @@ -318,7 +320,7 @@ class wxMBConvUTF7 : public wxMBConv @library{wxbase} @category{conv} - @see wxMBConvUTF7, @ref overview_mbconv "wxMBConv classes overview" + @see wxMBConvUTF7, @ref overview_mbconv */ class wxMBConvUTF8 : public wxMBConv { @@ -341,7 +343,7 @@ class wxMBConvUTF8 : public wxMBConv @library{wxbase} @category{conv} - @see wxMBConvUTF8, wxMBConvUTF32, @ref overview_mbconv "wxMBConv classes overview" + @see wxMBConvUTF8, wxMBConvUTF32, @ref overview_mbconv */ class wxMBConvUTF16 : public wxMBConv { @@ -362,7 +364,7 @@ class wxMBConvUTF16 : public wxMBConv @library{wxbase} @category{conv} - @see wxMBConvUTF8, wxMBConvUTF16, @ref overview_mbconv "wxMBConv classes overview" + @see wxMBConvUTF8, wxMBConvUTF16, @ref overview_mbconv */ class wxMBConvUTF32 : public wxMBConv { @@ -389,7 +391,7 @@ class wxMBConvUTF32 : public wxMBConv @library{wxbase} @category{conv} - @see wxMBConv, wxEncodingConverter, @ref overview_mbconv "wxMBConv classes overview" + @see wxMBConv, wxEncodingConverter, @ref overview_mbconv */ class wxCSConv : public wxMBConv { @@ -466,7 +468,7 @@ public: @library{wxbase} @category{conv} - @see @ref overview_mbconv "wxMBConv classes overview" + @see @ref overview_mbconv */ class wxMBConvFile : public wxMBConv { diff --git a/interface/wx/stream.h b/interface/wx/stream.h index f263607e4e..5d02acabb6 100644 --- a/interface/wx/stream.h +++ b/interface/wx/stream.h @@ -115,6 +115,7 @@ public: /** Constructor; creates a new empty stream buffer which won't flush any data to a stream. mode specifies the type of the buffer (read, write, read_write). + This stream buffer has the advantage to be stream independent and to work only on memory buffers but it is still compatible with the rest of the wxStream classes. You can write, read to this special stream and it will @@ -129,7 +130,9 @@ public: wxStreamBuffer(BufMode mode); /** - Constructor. It initializes the stream buffer with the data of the specified + Constructor. + + This method initializes the stream buffer with the data of the specified stream buffer. The new stream buffer has the same attributes, size, position and they share the same buffer. This will cause problems if the stream to which the stream buffer belong is destroyed and the newly cloned stream @@ -450,7 +453,7 @@ enum wxStreamProtocolType handle it and create a stream to decompress it: @code - factory = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT); + factory = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT); if (factory) stream = factory-NewStream(new wxFFileInputStream(filename)); @endcode diff --git a/interface/wx/string.h b/interface/wx/string.h index dd0c7d7d2e..7cf640a51f 100644 --- a/interface/wx/string.h +++ b/interface/wx/string.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: string.h -// Purpose: interface of wxStringBuffer +// Purpose: interface of wxStringBuffer, wxString // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -9,21 +9,19 @@ /** @class wxStringBuffer - This tiny class allows you to conveniently access the wxString - internal buffer as a writable pointer without any risk of forgetting to restore - the string to the usable state later. + This tiny class allows you to conveniently access the wxString internal buffer + as a writable pointer without any risk of forgetting to restore the string + to the usable state later. For example, assuming you have a low-level OS function called - @c GetMeaningOfLifeAsString(char *) returning the value in the provided + @c "GetMeaningOfLifeAsString(char *)" returning the value in the provided buffer (which must be writable, of course) you might call it like this: @code - wxString theAnswer; + wxString theAnswer; GetMeaningOfLifeAsString(wxStringBuffer(theAnswer, 1024)); if ( theAnswer != "42" ) - { wxLogError("Something is very wrong!"); - } @endcode Note that the exact usage of this depends on whether or not wxUSE_STL is @@ -41,15 +39,15 @@ class wxStringBuffer public: /** Constructs a writable string buffer object associated with the given string - and containing enough space for at least @a len characters. Basically, this - is equivalent to calling wxString::GetWriteBuf and + and containing enough space for at least @a len characters. + Basically, this is equivalent to calling wxString::GetWriteBuf() and saving the result. */ wxStringBuffer(const wxString& str, size_t len); /** Restores the string passed to the constructor to the usable state by calling - wxString::UngetWriteBuf on it. + wxString::UngetWriteBuf() on it. */ ~wxStringBuffer(); @@ -83,7 +81,7 @@ public: over a UTF-16 string under Windows, the user code has to take care of surrogate pair handling whereas Windows itself has built-in support pairs in UTF-16, such as for drawing strings on screen. - + Much work has been done to make existing code using ANSI string literals work as before. If you nonetheless need to have a wxString that uses wchar_t on Unix and Linux, too, you can specify this on the command line with the @@ -97,7 +95,7 @@ public: was also possible and encouraged by wxString using the access operator[]() wxString implements caching of the last used index so that iterating over a string is a linear operation even in UTF-8 mode. - + It is nonetheless recommended to use iterators (instead of index based access) like this: @@ -111,15 +109,14 @@ public: } @endcode - Please see the - @ref overview_string "wxString overview" and the - @ref overview_unicode "Unicode overview" for more information - about it. + Please see the @ref overview_string and the @ref overview_unicode for more + information about it. wxString uses the current locale encoding to convert any C string literal to Unicode. The same is done for converting to and from - @c std::string and for the return value of c_str(). For this - conversion, the @a wxConvLibc class instance is used. See wxCSConv and wxMBConv. + @c std::string and for the return value of c_str(). + For this conversion, the @a wxConvLibc class instance is used. + See wxCSConv and wxMBConv. wxString implements most of the methods of the @c std::string class. These standard functions are only listed here, but they are not @@ -132,172 +129,214 @@ public: all return the string length. In all cases of such duplication the @c std::string compatible method should be used. + + @section string_construct Constructors and assignment operators + + A string may be constructed either from a C string, (some number of copies of) + 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. + + @li wxString() + @li operator=() + @li ~wxString() + @li assign() + + + @section string_len String length + + These functions return the string length and check whether the string + is empty or they empty it. + + @li length() + @li size() + @li Len() + @li IsEmpty() + @li operator!() + @li Empty() + @li Clear() + + + @section string_access Character access + + Many functions below take a character index in the string. As with C + strings and arrays, the indices start from 0, so the first character of a + string is string[0]. An attempt to access a character beyond the end of the + string (which may even be 0 if the string is empty) will provoke an assert + failure in @ref overview_debugging "debug builds", 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, you are advised + to use wc_str() for the sake of clarity. + + @li GetChar() + @li GetWritableChar() + @li SetChar() + @li Last() + @li operator[]() + @li wc_str() + @li utf8_str() + @li c_str() + @li wx_str() + @li mb_str() + @li fn_str() + + + @section string_concat Concatenation + 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. - @li insert() - @li append() - @li operator<<() - @li operator+=() - @li operator+() - @li Append() - @li Prepend() - - A string may be constructed either from a C string, (some number of copies of) - 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. - - @li wxString() - @li operator=() - @li ~wxString() - @li assign() - - 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. - - @li MakeUpper() - @li Upper() - @li MakeLower() - @li Lower() - @li MakeCapitalized() - @li Capitalize() - - Many functions below take a character index in the string. As with C - strings and arrays, the indices start from 0, so the first character of a - string is string[0]. An attempt to access a character beyond the end of the - string (which may even be 0 if the string is empty) will provoke an assert - failure in @ref overview_debugging "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, you are advised - to use wc_str() for the sake of clarity. - - @li GetChar() - @li GetWritableChar() - @li SetChar() - @li Last() - @li operator[]() - @li wc_str() - @li utf8_str() - @li c_str() - @li wx_str() - @li mb_str() - @li fn_str() - - The default comparison function Cmp() is case-sensitive and so is the default - version of IsSameAs(). For case insensitive comparisons you should use CmpNoCase() - or give a second parameter to IsSameAs(). This last function is maybe more - convenient if only equality of the strings matters because it returns a boolean - @true value if the strings are the same and not 0 (which is usually @false - in C) as 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. - - @li compare() - @li Cmp() - @li CmpNoCase() - @li IsSameAs() - @li Matches() - @li StartsWith() - @li EndsWith() - - The string provides functions for conversion to signed and unsigned integer and - floating point numbers. All 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. - - @li ToLong() - @li ToLongLong() - @li ToULong() - @li ToULongLong() - @li ToDouble() - - The following are "advanced" functions and they will be needed rarely. - Alloc() and Shrink() are only interesting for optimization purposes. - wxStringBuffer and wxStringBufferLength classes may be very useful - when working with some external API which requires the caller to provide - a writable buffer. - - @li reserve() - @li resize() - @li Alloc() - @li Shrink() - @li wxStringBuffer - @li wxStringBufferLength - - Miscellaneous other string functions. - - @li Trim() - @li Truncate() - @li Pad() - - These functions return the string length and check whether the string - is empty or they empty it. - - @li length() - @li size() - @li Len() - @li IsEmpty() - @li operator!() - @li Empty() - @li Clear() - - These functions allow you to extract a substring from the string. The - original string is not modified and the function returns the extracted - substring. - - @li substr() - @li Mid() - @li operator()() - @li Left() - @li Right() - @li BeforeFirst() - @li BeforeLast() - @li AfterFirst() - @li AfterLast() - @li StartsWith() - @li EndsWith() - - These functions replace the standard @e strchr() and @e strstr() - functions. - - @li find() - @li rfind() - @li replace() - @li Find() - @li Replace() - - Both formatted versions (Printf/() and stream-like insertion operators - exist (for basic types only). Additionally, the Format() function allows - you to simply append a formatted value to a string: - - @li Format() - @li FormatV() - @li Printf() - @li PrintfV() - @li operator>>() - - The following functions are deprecated. Please consider using new wxWidgets 2.0 - functions instead (or, even better, @c std::string compatible variants). - - Contains(), First(), Freq(), IsAscii(), IsNull(), - IsNumber(), IsWord(), Last(), Length(), LowerCase(), Remove(), Strip(), - SubString(), UpperCase() + @li insert() + @li append() + @li operator<<() + @li operator+=() + @li operator+() + @li Append() + @li Prepend() + + + @section string_comp Comparison + + The default comparison function Cmp() is case-sensitive and so is the default + version of IsSameAs(). For case insensitive comparisons you should use CmpNoCase() + or give a second parameter to IsSameAs(). This last function is maybe more + convenient if only equality of the strings matters because it returns a boolean + @true value if the strings are the same and not 0 (which is usually @false + in C) as 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. + + @li compare() + @li Cmp() + @li CmpNoCase() + @li IsSameAs() + @li Matches() + @li StartsWith() + @li EndsWith() + + + @section string_substring Substring extraction + + These functions allow you to extract a substring from the string. The + original string is not modified and the function returns the extracted + substring. + + @li substr() + @li Mid() + @li operator()() + @li Left() + @li Right() + @li BeforeFirst() + @li BeforeLast() + @li AfterFirst() + @li AfterLast() + @li StartsWith() + @li EndsWith() + + + @section string_case Case conversion + + 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. + + @li MakeUpper() + @li Upper() + @li MakeLower() + @li Lower() + @li MakeCapitalized() + @li Capitalize() + + + @section string_search Searching and replacing + + These functions replace the standard @e strchr() and @e strstr() + functions. + + @li find() + @li rfind() + @li replace() + @li Find() + @li Replace() + + + @section string_conv Conversion to numbers + + The string provides functions for conversion to signed and unsigned integer and + floating point numbers. All 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. + + @li ToLong() + @li ToLongLong() + @li ToULong() + @li ToULongLong() + @li ToDouble() + + + @section string_fmt Writing values into the string + + Both formatted versions (Printf/() and stream-like insertion operators + exist (for basic types only). Additionally, the Format() function allows + you to simply append a formatted value to a string: + + @li Format() + @li FormatV() + @li Printf() + @li PrintfV() + @li operator>>() + + + @section string_mem Memory management + + The following are "advanced" functions and they will be needed rarely. + Alloc() and Shrink() are only interesting for optimization purposes. + wxStringBuffer and wxStringBufferLength classes may be very useful + when working with some external API which requires the caller to provide + a writable buffer. + + @li reserve() + @li resize() + @li Alloc() + @li Shrink() + @li wxStringBuffer + @li wxStringBufferLength + + + @section string_misc Miscellaneous + + Miscellaneous other string functions. + + @li Trim() + @li Truncate() + @li Pad() + + + @section string_misc wxWidgets 1.xx compatibility functions + + The following functions are deprecated. + Please consider using @c std::string compatible variants. + + Contains(), First(), Freq(), IsAscii(), IsNull(), + IsNumber(), IsWord(), Last(), Length(), LowerCase(), Remove(), Strip(), + SubString(), UpperCase() + @library{wxbase} @category{data} @stdobjects - ::Objects, ::wxEmptyString, + ::wxEmptyString - @see @ref overview_string "wxString overview", @ref overview_unicode - "Unicode overview", wxUString + @see @ref overview_string, @ref overview_unicode, wxUString */ class wxString { @@ -326,8 +365,8 @@ public: wxString(); /** - Creates a string from another string. Just increases the ref - count by 1. + Creates a string from another string. + Just increases the ref count by 1. */ wxString(const wxString& stringSrc); @@ -367,8 +406,8 @@ public: wxString(const wchar_t *pwz, size_t nLength); /** - Constructs a string from @e buf using the using - the current locale encoding to convert it to Unicode. + Constructs a string from @e buf using the using the current locale + encoding to convert it to Unicode. */ wxString(const wxCharBuffer& buf); @@ -390,8 +429,9 @@ public: /** - String destructor. Note that this is not virtual, so wxString must not be - inherited from. + String destructor. + + Note that this is not virtual, so wxString must not be inherited from. */ ~wxString(); @@ -488,7 +528,6 @@ public: */ wxString BeforeLast(wxUniChar ch) const; - /** Return the copy of the string with the first string character in the upper case and the subsequent ones in the lower case. @@ -1014,12 +1053,13 @@ public: Returns @true on success in which case the number is stored in the 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 @a base parameter. + 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 @a base parameter. @see ToDouble(), ToLong() */ @@ -1054,16 +1094,16 @@ public: //@{ /** Puts the string back into a reasonable state (in which it can be used - normally), after - GetWriteBuf() was called. + normally), after GetWriteBuf() was called. + 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 + + This method is deprecated, please use wxStringBuffer or wxStringBufferLength instead. */ void UngetWriteBuf(); @@ -1078,7 +1118,8 @@ public: wxString Upper() const; /** - The same as MakeUpper. + The same as MakeUpper(). + This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ @@ -1090,8 +1131,7 @@ public: Given this ambiguity it is mostly better to use wc_str(), mb_str() or utf8_str() instead. - Please see the @ref overview_unicode "Unicode overview" for more - information about it. + Please see the @ref overview_unicode for more information about it. Note that the returned value is not convertible to @c char* or @c wchar_t*, use char_str() or wchar_str() if you need to pass @@ -1125,7 +1165,9 @@ public: buffer will contain the conversion of the string to the encoding of the current locale (and so can fail). - @param len If non-@NULL, filled with the length of the returned buffer. + @param len + If non-@NULL, filled with the length of the returned buffer. + @return buffer containing the string contents in the specified type, notice that it may be @NULL if the conversion failed (e.g. Unicode @@ -1184,7 +1226,7 @@ public: wxString& operator<<(double d); /** - Same as Mid (substring extraction). + Same as Mid() (substring extraction). */ wxString operator ()(size_t start, size_t len); @@ -1389,15 +1431,9 @@ public: }; - /** - FIXME -*/ -wxString Objects: -; - -/** - FIXME + The global wxString instance of an empty string. + Used extensively in the entire wxWidgets API. */ wxString wxEmptyString; @@ -1407,27 +1443,27 @@ wxString wxEmptyString; /** @class wxStringBufferLength - This tiny class allows you to conveniently access the wxString - internal buffer as a writable pointer without any risk of forgetting to restore - the string to the usable state later, and allows the user to set the internal - length of the string. + This tiny class allows you to conveniently access the wxString internal buffer + as a writable pointer without any risk of forgetting to restore the string to + the usable state later, and allows the user to set the internal length of the string. For example, assuming you have a low-level OS function called - @c int GetMeaningOfLifeAsString(char *) copying the value in the provided + @c "int GetMeaningOfLifeAsString(char *)" copying the value in the provided buffer (which must be writable, of course), and returning the actual length of the string, you might call it like this: @code - wxString theAnswer; + wxString theAnswer; wxStringBuffer theAnswerBuffer(theAnswer, 1024); int nLength = GetMeaningOfLifeAsString(theAnswerBuffer); theAnswerBuffer.SetLength(nLength); if ( theAnswer != "42" ) - { wxLogError("Something is very wrong!"); - } @endcode + @todo + the example above does not make use of wxStringBufferLength?? + Note that the exact usage of this depends on whether or not wxUSE_STL is enabled. If wxUSE_STL is enabled, wxStringBuffer creates a separate empty character buffer, and if wxUSE_STL is disabled, it uses GetWriteBuf() from @@ -1435,7 +1471,8 @@ wxString wxEmptyString; relying on wxStringBuffer containing the old wxString data is not a good idea if you want to build your program both with and without wxUSE_STL. - Note that SetLength @c must be called before wxStringBufferLength destructs. + Note that wxStringBuffer::SetLength @b must be called before + wxStringBufferLength destructs. @library{wxbase} @category{data} @@ -1445,8 +1482,9 @@ class wxStringBufferLength public: /** Constructs a writable string buffer object associated with the given string - and containing enough space for at least @a len characters. Basically, this - is equivalent to calling wxString::GetWriteBuf and + and containing enough space for at least @a len characters. + + Basically, this is equivalent to calling wxString::GetWriteBuf and saving the result. */ wxStringBufferLength(const wxString& str, size_t len); @@ -1460,6 +1498,7 @@ public: /** Sets the internal length of the string referred to by wxStringBufferLength to @a nLength characters. + Must be called before wxStringBufferLength destructs. */ void SetLength(size_t nLength); diff --git a/interface/wx/sysopt.h b/interface/wx/sysopt.h index f29badc459..58eff6bc52 100644 --- a/interface/wx/sysopt.h +++ b/interface/wx/sysopt.h @@ -14,7 +14,103 @@ used to optimize behaviour that doesn't deserve a distinct API, but is still important to be able to configure. - These options are currently recognised by wxWidgets. + These options are currently recognised by wxWidgets: + + + @section sysopt_win Windows + + @beginFlagTable + @flag{no-maskblt} + 1 to never use WIN32's MaskBlt function, 0 to allow it to be used where possible. + Default: 0. In some circumstances the MaskBlt function can be slower than using + the fallback code, especially if using DC cacheing. By default, MaskBlt will be + used where it is implemented by the operating system and driver. + @flag{msw.remap} + If 1 (the default), wxToolBar bitmap colours will be remapped to the current + theme's values. Set this to 0 to disable this functionality, for example if + you're using more than 16 colours in your tool bitmaps. + @flag{msw.window.no-clip-children} + If 1, windows will not automatically get the WS_CLIPCHILDREN style. + This restores the way windows are refreshed back to the method used in + versions of wxWidgets earlier than 2.5.4, and for some complex window + hierarchies it can reduce apparent refresh delays. + You may still specify wxCLIP_CHILDREN for individual windows. + @flag{msw.notebook.themed-background} + If set to 0, globally disables themed backgrounds on notebook pages. + Note that this won't disable the theme on the actual notebook background + (noticeable only if there are no pages). + @flag{msw.staticbox.optimized-paint} + If set to 0, switches off optimized wxStaticBox painting. + Setting this to 0 causes more flicker, but allows applications to paint + graphics on the parent of a static box (the optimized refresh causes any + such drawing to disappear). + @flag{msw.display.directdraw} + If set to 1, use DirectDraw-based implementation of wxDisplay. + By default the standard Win32 functions are used. + @flag{msw.font.no-proof-quality} + If set to 1, use default fonts quality instead of proof quality when + creating fonts. With proof quality the fonts have slightly better + appearance but not all fonts are available in this quality, + e.g. the Terminal font in small sizes is not and this option may be + used if wider fonts selection is more important than higher quality. + @endFlagTable + + + @section sysopt_gtk GTK+ + + @beginFlagTable + @flag{gtk.tlw.can-set-transparent} + wxTopLevelWindow::CanSetTransparent() method normally tries to detect + automatically whether transparency for top level windows is currently + supported, however this may sometimes fail and this option allows to + override the automatic detection. Setting it to 1 makes the transparency + be always available (setting it can still fail, of course) and setting it + to 0 makes it always unavailable. + @flag{gtk.desktop} + This option can be set to override the default desktop environment + determination. Supported values are GNOME and KDE. + @flag{gtk.window.force-background-colour} + If 1, the backgrounds of windows with the wxBG_STYLE_COLOUR background + style are cleared forcibly instead of relying on the underlying GTK+ + window colour. This works around a display problem when running + applications under KDE with the gtk-qt theme installed (0.6 and below). + @endFlagTable + + + @section sysopt_mac Mac + + @beginFlagTable + @flag{mac.window-plain-transition} + If 1, uses a plainer transition when showing a window. + You can also use the symbol wxMAC_WINDOW_PLAIN_TRANSITION. + @flag{window-default-variant} + The default variant used by windows (cast to integer from the wxWindowVariant enum). + Also known as wxWINDOW_DEFAULT_VARIANT. + flag{mac.listctrl.always_use_generic} + Tells wxListCtrl to use the generic control even when it is capable of + using the native control instead. Also knwon as wxMAC_ALWAYS_USE_GENERIC_LISTCTRL. + @endFlagTable + + + @section sysopt_mgl MGL + + @beginFlagTable + @flag{mgl.aa-threshold} + Set this integer option to point size below which fonts are not antialiased. Default: 10. + @flag{mgl.screen-refresh} + Screen refresh rate in Hz. A reasonable default is used if not specified. + @endFlagTable + + + @section sysopt_motif Motif + + @beginFlagTable + @flag{motif.largebuttons} + If 1, uses a bigger default size for wxButtons. + @endFlagTable + + + The compile-time option to include or exclude this functionality is wxUSE_SYSTEM_OPTIONS. @library{wxbase} @category{misc} @@ -26,41 +122,41 @@ class wxSystemOptions : public wxObject { public: /** - Default constructor. You don't need to create an instance of wxSystemOptions - since all of its functions are static. + Default constructor. + + You don't need to create an instance of wxSystemOptions since all + of its functions are static. */ wxSystemOptions(); /** - Gets an option. The function is case-insensitive to @e name. + Gets an option. The function is case-insensitive to @a name. Returns empty string if the option hasn't been set. - @see SetOption(), GetOptionInt(), - HasOption() + @see SetOption(), GetOptionInt(), HasOption() */ static wxString GetOption(const wxString& name); /** - Gets an option as an integer. The function is case-insensitive to @e name. + Gets an option as an integer. The function is case-insensitive to @a name. If the option hasn't been set, this function returns 0. - @see SetOption(), GetOption(), - HasOption() + @see SetOption(), GetOption(), HasOption() */ static int GetOptionInt(const wxString& name); /** - Returns @true if the given option is present. The function is - case-insensitive to @e name. + Returns @true if the given option is present. + The function is case-insensitive to @a name. - @see SetOption(), GetOption(), - GetOptionInt() + @see SetOption(), GetOption(), GetOptionInt() */ static bool HasOption(const wxString& name); /** - 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 + 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. */ @@ -68,7 +164,7 @@ public: //@{ /** - Sets an option. The function is case-insensitive to @e name. + Sets an option. The function is case-insensitive to @a name. */ void SetOption(const wxString& name, const wxString& value); void SetOption(const wxString& name, int value); diff --git a/interface/wx/textdlg.h b/interface/wx/textdlg.h index e61352fe24..ccb4024f05 100644 --- a/interface/wx/textdlg.h +++ b/interface/wx/textdlg.h @@ -31,6 +31,8 @@ public: Parent window. @param message Message to show on the dialog. + @param caption + The caption of the dialog. @param defaultValue The default value, which may be the empty string. @param style -- 2.45.2