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
*/
{
public:
/**
- Constructor does nothing, use Walk() to walk the
- stack.
+ Constructor does nothing, use Walk() to walk the stack.
*/
wxStackWalker();
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);
@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
*/
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;
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;
/**
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;
/**
@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 <wx/generic/statbmpg.h>.
+
+ If you want to display larger images portably, you may use generic
+ implementation wxGenericStaticBitmap declared in \<wx/generic/statbmpg.h\>.
@library{wxcore}
@category{ctrl}
Default constructor
*/
wxStaticBitmap();
-
+
/**
Constructor, creating and showing a static bitmap control.
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()
*/
Default constructor
*/
wxStaticBox();
-
+
/**
Constructor, creating and showing a static box.
@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
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,
@endStyleTable
@library{wxcore}
- @category{FIXME}
+ @category{ctrl}
@see wxStaticBox
*/
Default constructor
*/
wxStaticLine();
-
+
/**
Constructor, creating and showing a static line.
@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.
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,
Default constructor.
*/
wxStaticText();
-
+
/**
Constructor, creating and showing a text control.
/**
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:
<TABLE>
<TR>
</TR>
<TR>
<TD><span></TD>
- <TD>generic formatter tag; see Pango Markup for more information.</TD>
+ <TD>generic formatter tag; see Pango Markup
+ (http://library.gnome.org/devel/pango/unstable/PangoMarkupFormat.html)
+ for more information.</TD>
</TR>
</TABLE>
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:
+
<TABLE>
<TR>
<TD>@b Special character</TD>
<TD>@c &gt;</TD>
</TR>
</TABLE>
-
+
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.
@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.
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()
*/
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);
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);
};
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);
};
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}
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);
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);
void CopyText(int length, const wxString& text);
/**
-
+
*/
bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
const wxPoint& pos = wxDefaultPosition,
int GetControlCharSymbol() const;
/**
-
+
*/
wxString GetCurLine(int* OUTPUT);
/**
-
+
*/
wxCharBuffer GetCurLineRaw(int* OUTPUT);
wxCharBuffer GetSelectedTextRaw();
/**
-
+
*/
void GetSelection(int* OUTPUT, int* OUTPUT);
int GetWrapVisualFlagsLocation() const;
/**
-
+
*/
int GetXOffset() const;
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();
void LineEndRectExtend();
/**
-
+
*/
void LineEndWrap();
/**
-
+
*/
void LineEndWrapExtend();
void ParaDown();
/**
-
+
*/
void ParaDownExtend();
/**
-
+
*/
void ParaUp();
/**
-
+
*/
void ParaUpExtend();
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);
void SetFoldMarginColour(bool useSetting, const wxColour& back);
/**
-
+
*/
void SetFoldMarginHiColour(bool useSetting, const wxColour& fore);
void SetKeyWords(int keywordSet, const wxString& keyWords);
/**
-
+
*/
void SetLastKeydownProcessed(bool val);
void VCHomeRectExtend();
/**
-
+
*/
void VCHomeWrap();
/**
-
+
*/
void VCHomeWrapExtend();
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
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:
/**
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
*/
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()
*/
/**
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
*/
/**
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
/**
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
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
*/
/**
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);
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.
*/
/**
@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());
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.
void Pause();
/**
- Resumes the stop watch which had been paused with
- Pause().
+ Resumes the stop watch which had been paused with Pause().
*/
void Resume();
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;
};
@library{wxbase}
@category{conv}
- @see wxCSConv, wxEncodingConverter, @ref overview_mbconv "wxMBConv classes overview"
+ @see wxCSConv, wxEncodingConverter, @ref overview_mbconv
*/
class wxMBConv
{
@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.
@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.
@library{wxbase}
@category{conv}
- @see wxMBConvUTF8, @ref overview_mbconv "wxMBConv classes overview"
+ @see wxMBConvUTF8, @ref overview_mbconv
*/
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
{
@library{wxbase}
@category{conv}
- @see wxMBConvUTF8, wxMBConvUTF32, @ref overview_mbconv "wxMBConv classes overview"
+ @see wxMBConvUTF8, wxMBConvUTF32, @ref overview_mbconv
*/
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
{
@library{wxbase}
@category{conv}
- @see wxMBConv, wxEncodingConverter, @ref overview_mbconv "wxMBConv classes overview"
+ @see wxMBConv, wxEncodingConverter, @ref overview_mbconv
*/
class wxCSConv : public wxMBConv
{
@library{wxbase}
@category{conv}
- @see @ref overview_mbconv "wxMBConv classes overview"
+ @see @ref overview_mbconv
*/
class wxMBConvFile : public wxMBConv
{
/**
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
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
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
/////////////////////////////////////////////////////////////////////////////
// Name: string.h
-// Purpose: interface of wxStringBuffer
+// Purpose: interface of wxStringBuffer, wxString
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
/**
@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
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();
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
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:
}
@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
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
{
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);
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);
/**
- 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();
*/
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.
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()
*/
//@{
/**
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();
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.
*/
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
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
wxString& operator<<(double d);
/**
- Same as Mid (substring extraction).
+ Same as Mid() (substring extraction).
*/
wxString operator ()(size_t start, size_t len);
};
-
/**
- FIXME
-*/
-wxString Objects:
-;
-
-/**
- FIXME
+ The global wxString instance of an empty string.
+ Used extensively in the entire wxWidgets API.
*/
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
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}
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);
/**
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);
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}
{
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.
*/
//@{
/**
- 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);
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
projects / wxWidgets.git / commitdiff
