Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Doc fixes

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@1800 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Julian Smart
1999-02-26 17:29:39 +00:00
parent 3a2629c0a2
commit 532372a31c
4 changed files with 62 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
docs/latex/wx/function.tex
View File

@@ -37,15 +37,17 @@ Returns TRUE if the file exists.
\func{wxString}{wxFileNameFromPath}{\param{const wxString\& }{path}} \func{wxString}{wxFileNameFromPath}{\param{const wxString\& }{path}}
Returns a temporary pointer to the filename for a full path. \func{char*}{wxFileNameFromPath}{\param{char* }{path}}
Copy this pointer for long-term use.
Returns the filename for a full path. The second form returns a pointer to
temporary storage that should not be deallocated.
\membersection{::wxFindFirstFile}\label{wxfindfirstfile} \membersection{::wxFindFirstFile}\label{wxfindfirstfile}
\func{wxString}{wxFindFirstFile}{\param{const wxString\& }{spec}, \param{int}{ flags = 0}} \func{wxString}{wxFindFirstFile}{\param{const char*}{spec}, \param{int}{ flags = 0}}
This function does directory searching; returns the first file This function does directory searching; returns the first file
that matches the path {\it spec}, or NULL. Use \helpref{wxFindNextFile}{wxfindnextfile} to that matches the path {\it spec}, or the empty string. Use \helpref{wxFindNextFile}{wxfindnextfile} to
get the next matching file. get the next matching file.
{\it spec} may contain wildcards. {\it spec} may contain wildcards.
@@ -59,7 +61,7 @@ For example:
\begin{verbatim} \begin{verbatim}
wxString f = wxFindFirstFile("/home/project/*.*"); wxString f = wxFindFirstFile("/home/project/*.*");
while (f) while (f != "")
{ {
... ...
f = wxFindNextFile(); f = wxFindNextFile();
@@ -89,8 +91,7 @@ or drive name at the beginning.
\func{wxString}{wxPathOnly}{\param{const wxString\& }{path}} \func{wxString}{wxPathOnly}{\param{const wxString\& }{path}}
Returns a temporary pointer to the directory part of the filename. Copy this Returns the directory part of the filename.
pointer for long-term use.
\membersection{::wxUnix2DosFilename} \membersection{::wxUnix2DosFilename}
@@ -168,7 +169,7 @@ Returns TRUE if successful, FALSE otherwise.
\membersection{::wxGetWorkingDirectory} \membersection{::wxGetWorkingDirectory}
\func{wxString}{wxGetWorkingDirectory}{\param{const wxString\& }{buf=NULL}, \param{int }{sz=1000}} \func{wxString}{wxGetWorkingDirectory}{\param{char*}{buf=NULL}, \param{int }{sz=1000}}
This function is obsolete: use \helpref{wxGetCwd}{wxgetcwd} instead. This function is obsolete: use \helpref{wxGetCwd}{wxgetcwd} instead.
@@ -180,7 +181,7 @@ if the buffer is NULL.
\membersection{::wxGetTempFileName} \membersection{::wxGetTempFileName}
\func{wxString}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{const wxString\& }{buf=NULL}} \func{char*}{wxGetTempFileName}{\param{const wxString\& }{prefix}, \param{char* }{buf=NULL}}
Makes a temporary filename based on {\it prefix}, opens and closes the file, Makes a temporary filename based on {\it prefix}, opens and closes the file,
and places the name in {\it buf}. If {\it buf} is NULL, new store and places the name in {\it buf}. If {\it buf} is NULL, new store
@@ -371,7 +372,7 @@ if other wxWindows calls will be made before the value is to be used.
Pop up a dialog box with title set to {\it caption}, message {\it message}, and a Pop up a dialog box with title set to {\it caption}, message {\it message}, and a
\rtfsp{\it default\_value}. The user may type in text and press OK to return this text, \rtfsp{\it default\_value}. The user may type in text and press OK to return this text,
or press Cancel to return NULL. or press Cancel to return the empty string.
If {\it centre} is TRUE, the message text (which may include new line characters) If {\it centre} is TRUE, the message text (which may include new line characters)
is centred; if FALSE, the message is left-justified. is centred; if FALSE, the message is left-justified.
@@ -414,7 +415,7 @@ is centred; if FALSE, the message is left-justified.
Pops up a dialog box containing a message, OK/Cancel buttons and a single-selection Pops up a dialog box containing a message, OK/Cancel buttons and a single-selection
listbox. The user may choose an item and press OK to return a string or listbox. The user may choose an item and press OK to return a string or
Cancel to return NULL. Cancel to return the empty string.
{\it choices} is an array of {\it n} strings for the listbox. {\it choices} is an array of {\it n} strings for the listbox.

8
docs/latex/wx/tdelwin.tex
View File

@@ -3,7 +3,7 @@
Classes: \helpref{wxCloseEvent}{wxcloseevent}, \helpref{wxWindow}{wxwindow} Classes: \helpref{wxCloseEvent}{wxcloseevent}, \helpref{wxWindow}{wxwindow}
Window deletion can be a confusing subject, so this overview is provided Window deletion can be a confusing subject, so this overview is provided
to make it clear when and how you delete windows, or respond to user requests to help make it clear when and how you delete windows, or respond to user requests
to close windows. to close windows.
\wxheading{What is the sequence of events in a window deletion?} \wxheading{What is the sequence of events in a window deletion?}
@@ -27,6 +27,10 @@ delete the window, and not use the {\bf delete} operator. This is because
for some window classes, wxWindows delays actual deletion of the window until all events have been processed, for some window classes, wxWindows delays actual deletion of the window until all events have been processed,
since otherwise there is the danger that events will be sent to a non-existent window. since otherwise there is the danger that events will be sent to a non-existent window.
As reinforced in the next section, calling Close does not guarantee that the window
will be destroyed. Call \helpref{wxWindow::Destroy}{wxwindowdestroy} if you want to be
certain that the window is destroyed.
\wxheading{How can the application close a window itself?} \wxheading{How can the application close a window itself?}
Your application can either use \helpref{wxWindow::Close}{wxwindowclose} event just as Your application can either use \helpref{wxWindow::Close}{wxwindowclose} event just as
@@ -45,7 +49,7 @@ The default close event handler for wxDialog simulates a Cancel command,
generating a wxID\_CANCEL event. Since the handler for this cancel event might generating a wxID\_CANCEL event. Since the handler for this cancel event might
itself call {\bf Close}, there is a check for infinite looping. The default handler itself call {\bf Close}, there is a check for infinite looping. The default handler
for wxID\_CANCEL hides the dialog (if modeless) or calls EndModal(wxID\_CANCEL) (if modal). for wxID\_CANCEL hides the dialog (if modeless) or calls EndModal(wxID\_CANCEL) (if modal).
In other words, by default, the dialog is not destroyed (it might have been created In other words, by default, the dialog {\it is not destroyed} (it might have been created
on the stack, so the assumption of dynamic creation cannot be made). on the stack, so the assumption of dynamic creation cannot be made).
The default close event handler for wxFrame destroys the frame using Destroy(). The default close event handler for wxFrame destroys the frame using Destroy().

73
docs/latex/wx/tstring.tex
View File

@@ -4,52 +4,51 @@ Classes: \helpref{wxString}{wxstring}, \helpref{wxArrayString}{wxarray}, \helpre
\subsection{Introduction} \subsection{Introduction}
wxString is a class which represents a character string of arbitrary (limited by wxString is a class which represents a character string of arbitrary length (limited by
{\it MAX\_INT} which is usually 2147483647 on 32 bit machines) length and containing {\it MAX\_INT} which is usually 2147483647 on 32 bit machines) and containing
arbitrary characters (i.e. ASCII NUL character is allowed, although care should be arbitrary characters. The ASCII NUL character is allowed, although care should be
taken when passing strings containing it to other functions). taken when passing strings containing it to other functions.
wxString only works with ASCII (8 bit characters) strings as of this release, wxString only works with ASCII (8 bit characters) strings as of this release,
however support for UNICODE (16 but characters) is planned for the next one. but support for UNICODE (16 but characters) is planned for the next one.
This class has all standard operations you can expect to find in a string class: This class has all the standard operations you can expect to find in a string class:
dynamic memory management (string extends to accomodate new characters), dynamic memory management (string extends to accomodate new characters),
construction from other strings, C strings and characters, assignment operators, construction from other strings, C strings and characters, assignment operators,
access to separate characters, string concatenation and comparison, substring access to individual characters, string concatenation and comparison, substring
extraction, case conversion, trimming and padding (with spaces), searching and extraction, case conversion, trimming and padding (with spaces), searching and
replacing and both C-like \helpref{Printf()}{wxstringprintf} and stream-like replacing and both C-like \helpref{Printf()}{wxstringprintf} and stream-like
insertion functions as well as much else - see \helpref{wxString}{wxstring} insertion functions as well as much more - see \helpref{wxString}{wxstring}
for the list of all functions. for a list of all functions.
\subsection{Comparison of wxString to other string classes} \subsection{Comparison of wxString to other string classes}
The advantages of using a special string class instead of working directly with The advantages of using a special string class instead of working directly with
C strings are so obvious (the most imoprtant being, of course, the need to always C strings are so obvious that there is a huge number of such classes available.
remember to allocate/free memory for C strings unless the programmer prefers The most important advantage is the need to always
working with fixed size buffers which almost certainly leads to the dreaded remember to allocate/free memory for C strings; working with fixed size buffers almost inevitably leads to buffer overflows).
buffer overflows) that there is a huge number of such classes available and now, At last, C++ has a standard string class (std::string). So why the need for wxString?
finally, C++ even has one (std::string) in standard. Why use wxString then?
There are several advantages: There are several advantages:
\begin{enumerate}\itemsep=0pt \begin{enumerate}\itemsep=0pt
\item {\bf Efficiency} This class was made to be as efficient as possible: both \item {\bf Efficiency} This class was made to be as efficient as possible: both
in terms of size (each wxString objects takes exactly the same place as {\it in terms of size (each wxString objects takes exactly the same space as a {\it
char *} pointer, \helpref{reference counting}{wxstringrefcount}) and speed. char *} pointer, sing \helpref{reference counting}{wxstringrefcount}) and speed.
It also provides performance \helpref{statistics gathering code}{wxstringtuning} It also provides performance \helpref{statistics gathering code}{wxstringtuning}
which may be enabled to fine tune the memory allocation strategy for your which may be enabled to fine tune the memory allocation strategy for your
particular application - and the gain might be quite big. particular application - and the gain might be quite big.
\item {\bf Compatibility} This class tries to combine almost full compatibility \item {\bf Compatibility} This class tries to combine almost full compatibility
with the old wxWindows 1.xx wxString class, some reminiscence to MFC CString with the old wxWindows 1.xx wxString class, some reminiscence to MFC CString
class and 90\% of functionality of std::string class. class and 90\% of the functionality of std::string class.
\item {\bf Rich set of functions} Some of the functions present in wxString are \item {\bf Rich set of functions} Some of the functions present in wxString are
very useful but don't exist in most of other string classes: for example, very useful but don't exist in most of other string classes: for example,
\helpref{AfterFirst}{wxstringafterfirst}, \helpref{AfterFirst}{wxstringafterfirst},
\helpref{BeforeLast}{wxstringbeforelast}, \helpref{operator<<}{wxstringoperatorout} \helpref{BeforeLast}{wxstringbeforelast}, \helpref{operator<<}{wxstringoperatorout}
or \helpref{Printf}{wxstringprintf}. Of course, all the standard string or \helpref{Printf}{wxstringprintf}. Of course, all the standard string
operations are supported as well. operations are supported as well.
\item {\bf UNICODE} In this release, wxString only supports construction from \item {\bf UNICODE} In this release, wxString only supports {\it construction} from
an UNICODE string, but in the next one it will be capable of also storing its a UNICODE string, but in the next one it will be capable of also storing its
internal data in either ASCII or UNICODE format. internal data in either ASCII or UNICODE format.
\item {\bf Used by wxWindows} And, of course, this class is used everywhere \item {\bf Used by wxWindows} And, of course, this class is used everywhere
inside wxWindows so there is no performance loss which would result from inside wxWindows so there is no performance loss which would result from
@@ -73,15 +72,15 @@ in both wxWindows and other programs (by just typedefing wxString as std::string
when used outside wxWindows) and by staying compatible with future versions of when used outside wxWindows) and by staying compatible with future versions of
wxWindows which will probably start using std::string sooner or later too. wxWindows which will probably start using std::string sooner or later too.
In the situations when there is no correspondinw std::string function, please In the situations where there is no correspondinw std::string function, please
try to use the new wxString methods and not the old wxWindows 1.xx variants try to use the new wxString methods and not the old wxWindows 1.xx variants
which are deprecated and risk to disappear in future versions. which are deprecated and may disappear in future versions.
\subsection{Some advice about using wxString}\label{wxstringadvices} \subsection{Some advice about using wxString}\label{wxstringadvices}
Probably the main trap with using this class is the implicit conversion operator to Probably the main trap with using this class is the implicit conversion operator to
{\it const char *}. It is advised that you use \helpref{c\_str()}{wxstringcstr} {\it const char *}. It is advised that you use \helpref{c\_str()}{wxstringcstr}
instead of it to clearly indicate when the conversion is done. Specifically, the instead to clearly indicate when the conversion is done. Specifically, the
danger of this implicit conversion may be seen in the following code fragment: danger of this implicit conversion may be seen in the following code fragment:
\begin{verbatim} \begin{verbatim}
@@ -120,7 +119,7 @@ The second bug is that returning {\it output} doesn't work. The implicit cast is
used again, so the code compiles, but as it returns a pointer to a buffer used again, so the code compiles, but as it returns a pointer to a buffer
belonging to a local variable which is deleted as soon as the function exits, belonging to a local variable which is deleted as soon as the function exits,
its contents is totally arbitrary. The solution to this problem is also easy: its contents is totally arbitrary. The solution to this problem is also easy:
just make the function return wxString instead of C string. just make the function return wxString instead of a C string.
This leads us to the following general advice: all functions taking string This leads us to the following general advice: all functions taking string
arguments should take {\it const wxString\&} (this makes assignment to the arguments should take {\it const wxString\&} (this makes assignment to the
@@ -131,13 +130,13 @@ variables.
\subsection{Other string related functions and classes} \subsection{Other string related functions and classes}
As any program operates with character strings, the standard C library provides quite a As most programs use character strings, the standard C library provides quite a
few of functions to work with them. Unfortunately, some of them have rather non few functions to work with them. Unfortunately, some of them have rather
intuitive behaviour (like strncpy() which doesn't always terminate the resulting counter-intuitive behaviour (like strncpy() which doesn't always terminate the resulting
string with a NUL) and are in general not very safe (passing NULL to them will string with a NULL) and are in general not very safe (passing NULL to them will
probably lead to program crash). Moreover, some of very useful functions are not probably lead to program crash). Moreover, some very useful functions are not
standard at all. This is why in addition to all wxString functions, there are standard at all. This is why in addition to all wxString functions, there are
also a few of global string functions which try to correct these problems: also a few global string functions which try to correct these problems:
\helpref{IsEmpty()}{wxstringisempty} verifies whether the string is empty (returning \helpref{IsEmpty()}{wxstringisempty} verifies whether the string is empty (returning
TRUE for NULL pointers), \helpref{Strlen()}{wxstringstrlen} also handles NULLs correctly TRUE for NULL pointers), \helpref{Strlen()}{wxstringstrlen} also handles NULLs correctly
and returns 0 for them and \helpref{Stricmp()}{wxstringstricmp} is just a and returns 0 for them and \helpref{Stricmp()}{wxstringstricmp} is just a
@@ -149,17 +148,17 @@ There is another class which might be useful when working with wxString:
be broken into tokens and replaces the standard C library {\it be broken into tokens and replaces the standard C library {\it
strtok()} function. strtok()} function.
And the very last string related class is \helpref{wxArrayString}{wxarray}: it And the very last string-related class is \helpref{wxArrayString}{wxarray}: it
is just a version of the "template" dynamic array class which is specialized to work is just a version of the "template" dynamic array class which is specialized to work
with strings. Please note that this class is specially optimized (it uses its with strings. Please note that this class is specially optimized (using its
knowledge of internal structure of wxString) for storing strings and so it is knowledge of the internal structure of wxString) for storing strings and so it is
vastly better from performance point of view than wxObjectArray of wxString. vastly better from a performance point of view than a wxObjectArray of wxStrings.
\subsection{Reference counting and why you shouldn't care about it}\label{wxstringrefcount} \subsection{Reference counting and why you shouldn't care about it}\label{wxstringrefcount}
wxString objects use a technique known as {\it copy on write} (COW). This means wxString objects use a technique known as {\it copy on write} (COW). This means
that when a string is assigned to another, no copying really takes place: only that when a string is assigned to another, no copying really takes place: only
the reference count on the shared string data is increased and both strings the reference count on the shared string data is incremented and both strings
share the same data. share the same data.
But as soon as one of the two (or more) strings is modified, the data has to be But as soon as one of the two (or more) strings is modified, the data has to be
@@ -183,8 +182,8 @@ call to this operator may modify the string, its data is unshared (COW is done)
and so if the string was really shared there is some performance loss (both in and so if the string was really shared there is some performance loss (both in
terms of speed and memory consumption). In the rare cases when this may be terms of speed and memory consumption). In the rare cases when this may be
important, you might prefer using \helpref{GetChar()}{wxstringgetchar} instead important, you might prefer using \helpref{GetChar()}{wxstringgetchar} instead
of array subscript operator for this reasons. Please note that of the array subscript operator for this reasons. Please note that
\helpref{at()}{wxstringat} method has the same problem as subscript operator in \helpref{at()}{wxstringat} method has the same problem as the subscript operator in
this situation and so using it is not really better. Also note that if all this situation and so using it is not really better. Also note that if all
string arguments to your functions are passed as {\it const wxString\&} (see the string arguments to your functions are passed as {\it const wxString\&} (see the
section \helpref{Some advice}{wxstringadvices}) this situation will almost section \helpref{Some advice}{wxstringadvices}) this situation will almost
@@ -200,7 +199,7 @@ also read the preceding section about
For the performance reasons wxString doesn't allocate exactly the amount of For the performance reasons wxString doesn't allocate exactly the amount of
memory needed for each string. Instead, it adds a small amount of space to each memory needed for each string. Instead, it adds a small amount of space to each
allocated block which allows it to not reallocate memory (this is a relatively allocated block which allows it to not reallocate memory (a relatively
expensive operation) too often as when, for example, a string is constructed by expensive operation) too often as when, for example, a string is constructed by
subsequently adding one character at a time to it, as for example in: subsequently adding one character at a time to it, as for example in:

8
docs/latex/wx/window.tex
View File

@@ -196,6 +196,14 @@ destroy the window using \helpref{wxWindow::Destroy}{wxwindowdestroy}.
Applies to managed windows (wxFrame and wxDialog classes) only. Applies to managed windows (wxFrame and wxDialog classes) only.
{\it Note} that calling Close does not guarantee that the window will be destroyed; but it
provides a way to simulate a manual close of a window, which may or may not be implemented by
destroying the window. The default implementation of wxDialog::OnCloseWindow does not
necessarily delete the dialog, since it will simply simulate an wxID\_CANCEL event which
itself only hides the dialog.
To guarantee that the window will be destroyed, call \helpref{wxWindow::Destroy}{wxwindowdestroy} instead.
\wxheading{See also} \wxheading{See also}
\helpref{Window deletion overview}{windowdeletionoverview},\rtfsp \helpref{Window deletion overview}{windowdeletionoverview},\rtfsp