Constructs a wxClassInfo object. The supplied macros implicitly construct objects of this
class, so there is no need to create such objects explicitly in an application.
-\membersection{wxClassInfo::CreateObject}
+\membersection{wxClassInfo::CreateObject}\label{wxclassinfocreateobject}
\func{wxObject*}{CreateObject}{\void}
\input sashevt.tex
\input sashlayw.tex
\input sashwin.tex
-\input screendc.tex
\input scpdarry.tex
\input scpdptr.tex
+\input screendc.tex
\input scrolbar.tex
\input scrolwin.tex
\input scrolevt.tex
\func{}{wxCSConv}{\param{const wxChar* }{charset}}
-\func{}{wxCSConv}{\param{wxFontEncoding}{encoding}}
+\func{}{wxCSConv}{\param{wxFontEncoding }{encoding}}
Constructor. You may specify either the name of the character set you want to
convert from/to or an encoding constant. If the character set name is not
\constfunc{size\_t}{MB2WC}{\param{wchar\_t* }{buf}, \param{const char* }{psz}, \param{size\_t }{n}}
-Converts from the selected character set to Unicode. Returns the size of the destination buffer.
-
+Converts from the selected character set to Unicode. Returns length of string written to destination buffer.
\membersection{wxCSConv::WC2MB}\label{wxcsconvwc2mb}
\constfunc{size\_t}{WC2MB}{\param{char* }{buf}, \param{const wchar\_t* }{psz}, \param{size\_t }{n}}
-Converts from Unicode to the selected character set. Returns the size of the destination buffer.
-
+Converts from Unicode to the selected character set. Returns length of string written to destination buffer.
\constfunc{bool}{IsGregorianDate}{\param{GregorianAdoption }{country = Gr\_Standard}}
-Returns {\tt true} if the given date os later than the date of adoption of the
+Returns {\tt true} if the given date is later than the date of adoption of the
Gregorian calendar in the given country (and hence the Gregorian calendar
calculations make sense for it).
bottom up orientation, false to invert it.}
-\membersection{wxDC::SetDeviceOrigin}\label{wxdcsetdeviceorigin}
-
-\func{void}{SetDeviceOrigin}{\param{wxCoord}{ x}, \param{wxCoord}{ y}}
-
-Sets the device origin (i.e., the origin in pixels after scaling has been
-applied).
-
-This function may be useful in Windows printing
-operations for placing a graphic on a page.
-
-
\membersection{wxDC::SetBackground}\label{wxdcsetbackground}
\func{void}{SetBackground}{\param{const wxBrush\& }{brush}}
whether text will be drawn with a background colour or not.
+\membersection{wxDC::SetBrush}\label{wxdcsetbrush}
+
+\func{void}{SetBrush}{\param{const wxBrush\& }{brush}}
+
+Sets the current brush for the DC.
+
+If the argument is wxNullBrush, the current brush is selected out of the device
+context, and the original brush restored, allowing the current brush to
+be destroyed safely.
+
+See also \helpref{wxBrush}{wxbrush}.
+
+See also \helpref{wxMemoryDC}{wxmemorydc} for the interpretation of colours
+when drawing into a monochrome bitmap.
+
+
\membersection{wxDC::SetClippingRegion}\label{wxdcsetclippingregion}
\func{void}{SetClippingRegion}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxCoord}{ width}, \param{wxCoord}{ height}}
\helpref{wxDC::DestroyClippingRegion}{wxdcdestroyclippingregion}, \helpref{wxRegion}{wxregion}
-\membersection{wxDC::SetPalette}\label{wxdcsetpalette}
-
-\func{void}{SetPalette}{\param{const wxPalette\& }{palette}}
-
-If this is a window DC or memory DC, assigns the given palette to the window
-or bitmap associated with the DC. If the argument is wxNullPalette, the current
-palette is selected out of the device context, and the original palette
-restored.
-
-See \helpref{wxPalette}{wxpalette} for further details.
-
-
-\membersection{wxDC::SetBrush}\label{wxdcsetbrush}
-
-\func{void}{SetBrush}{\param{const wxBrush\& }{brush}}
-
-Sets the current brush for the DC.
+\membersection{wxDC::SetDeviceOrigin}\label{wxdcsetdeviceorigin}
-If the argument is wxNullBrush, the current brush is selected out of the device
-context, and the original brush restored, allowing the current brush to
-be destroyed safely.
+\func{void}{SetDeviceOrigin}{\param{wxCoord}{ x}, \param{wxCoord}{ y}}
-See also \helpref{wxBrush}{wxbrush}.
+Sets the device origin (i.e., the origin in pixels after scaling has been
+applied).
-See also \helpref{wxMemoryDC}{wxmemorydc} for the interpretation of colours
-when drawing into a monochrome bitmap.
+This function may be useful in Windows printing
+operations for placing a graphic on a page.
\membersection{wxDC::SetFont}\label{wxdcsetfont}
that must occasionally be employed.
+\membersection{wxDC::SetPalette}\label{wxdcsetpalette}
+
+\func{void}{SetPalette}{\param{const wxPalette\& }{palette}}
+
+If this is a window DC or memory DC, assigns the given palette to the window
+or bitmap associated with the DC. If the argument is wxNullPalette, the current
+palette is selected out of the device context, and the original palette
+restored.
+
+See \helpref{wxPalette}{wxpalette} for further details.
+
+
\membersection{wxDC::SetPen}\label{wxdcsetpen}
\func{void}{SetPen}{\param{const wxPen\& }{pen}}
\param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}}
Connects the given function dynamically with the event handler, id and event type. This
-is an alternative to the use of static event tables. See the 'dynamic' sample for usage.
+is an alternative to the use of static event tables. See the 'event' or the old 'dynamic' sample for usage.
\wxheading{Parameters}
\constfunc{wxString}{GetVolume}{\void}
-Returns the string containing the volume for this file name, mepty if it
+Returns the string containing the volume for this file name, empty if it
doesn't have one or if the file system doesn't support volumes at all (for
example, Unix).
\helpref{wxGetCwd}{wxgetcwd}\\
\helpref{wxGetDiskSpace}{wxgetdiskspace}\\
\helpref{wxGetDisplayName}{wxgetdisplayname}\\
+\helpref{wxGetDisplaySize}{wxdisplaysize}\\
+\helpref{wxGetDisplaySizeMM}{wxdisplaysizemm}\\
\helpref{wxGetElapsedTime}{wxgetelapsedtime}\\
\helpref{wxGetEmailAddress}{wxgetemailaddress}\\
\helpref{wxGetEnv}{wxgetenv}\\
get the next matching file. Neither will report the current directory "." or the
parent directory "..".
+\wxheading{Warning}
+
+As of wx 2.5.2, these functions are not thread-safe! (use static variables)
+
{\it spec} may contain wildcards.
{\it flags} may be wxDIR for restricting the query to directories, wxFILE for files or zero for either.
\item wxTRACE\_OleCalls: trace OLE method calls (Win32 only)
\end{itemize}
-The third version of the function only logs the message if all the bit
+{\bf Caveats:} since both the mask and the format string are strings,
+this might lead to function signature confusion in some cases:
+if you intend to call the format string only version of wxLogTrace,
+then add a \%s format string parameter and then supply a second string parameter for that \%s, the string mask version of wxLogTrace will erroneously get called instead, since you are supplying two string parameters to the function.
+In this case you'll unfortunately have to avoid having two leading
+string parameters, e.g. by adding a bogus integer (with its \%d format string).
+
+The third version of the function only logs the message if all the bits
corresponding to the {\it mask} are set in the wxLog trace mask which can be
set by \helpref{SetTraceMask}{wxlogsettracemask}. This version is less
flexible than the previous one because it doesn't allow defining the user
\func{}{wxHashMap}{\param{size\_type}{ size = 10}}
-The size parameter is just an hint, the table will resize automatically
+The size parameter is just a hint, the table will resize automatically
to preserve performance.
\func{}{wxHashMap}{\param{const wxHashMap\&}{ map}}
\func{size\_type}{erase}{\param{const key\_type\&}{ key}}
-Erases the element with the given key, and returns the number of element
+Erases the element with the given key, and returns the number of elements
erased (either 0 or 1).
\func{void}{erase}{\param{iterator}{ it}}
\constfunc{size\_type}{size}{}
-Returns the numbers of elements in the map.
+Returns the number of elements in the map.
handler.
In emergencies the \helpref{wxExit}{wxexit} function can be called to kill the
-application however normally the applications shuts down automatically,
+application however normally the application shuts down automatically,
\helpref{see below}{wxappshutdownoverview}.
An example of defining an application follows:
moment -- is closed.
-Another aspect of the application shutdown is the \helpref{OnExit}{wxapponexit}
+Another aspect of the application shutdown is \helpref{OnExit}{wxapponexit}
which is called when the application exits but {\it before} wxWidgets cleans up
-its internal structures. Your should delete all wxWidgets object that your
+its internal structures. You should delete all wxWidgets object that you
created by the time OnExit finishes. In particular, do {\bf not} destroy them
from application class' destructor!
to make them easy to use within an application.
Some dialogs have both platform-dependent and platform-independent implementations,
-so that if underlying windowing systems that do not provide the required functionality,
+so that if underlying windowing systems do not provide the required functionality,
the generic classes and functions can stand in. For example, under MS Windows, wxColourDialog
uses the standard colour selector. There is also an equivalent called wxGenericColourDialog
for other platforms, and a macro defines wxColourDialog to be the same as wxGenericColourDialog
\helpref{wxList::DeleteContents}{wxlistdeletecontents} method.
Dynamic arrays resemble C arrays but with two important differences: they
-provide run-time range checking in debug builds and they expand automatically
+provide run-time range checking in debug builds and they automatically expand
the allocated memory when there is no more space for new items. They come in
two sorts: the "plain" arrays which store either built-in types such as "char",
"int" or "bool" or the pointers to arbitrary objects, or "object arrays" which
\begin{twocollist}\itemsep=0pt
\twocolitem{\tt{WXTRACE}}{(Debug build only.)
-This variable can be set to comma-separated list of trace masks used in
+This variable can be set to a comma-separated list of trace masks used in
\helpref{wxLogTrace}{wxlogtrace} calls;
\helpref{wxLog::AddTraceMask}{wxlogaddtracemask} is called for every mask
in the list during wxWidgets initialization.}
\twocolitem{\tt{WXPREFIX}}{(Unix only.)
Overrides installation prefix. Normally, the prefix
-is hard-coded and is same as the value passed to {\tt configure} via
+is hard-coded and is the same as the value passed to {\tt configure} via
the {\tt --prefix} switch when compiling the library (typically
{\tt /usr/local} or {\tt /usr}). You can set WXPREFIX if you are for example
-distributing binary version of an application and you don't know in advance
+distributing a binary version of an application and you don't know in advance
where it will be installed.}
\twocolitem{\tt{WXMODE}}{(wxMGL only.)
note that we will only discuss 8-bit fonts here and not
\helpref{Unicode}{unicode}.
-Font encoding support is assured by several classes:
+Font encoding support is ensured by several classes:
\helpref{wxFont}{wxfont} itself, but also
\helpref{wxFontEnumerator}{wxfontenumerator} and
\helpref{wxFontMapper}{wxfontmapper}. wxFont encoding support is reflected by
This class stores the mapping between the encodings and the font face
names which support them in \helpref{wxConfig}{wxconfigoverview} object. Of
course, it would be fairly useless if it tried to determine these mappings by
-itself, so, instead, it (optionally) ask the user and remember his answers
+itself, so, instead, it (optionally) asks the user and remembers his answers
so that the next time the program will automatically choose the correct font.
All these topics are illustrated by the \helpref{font sample}{samplefont};
DDE-based or socket-based implementation is used and the same
thing for {\tt wxClient} and {\tt wxConnection}.
-By default, DDE implementation is used under Windows. DDE works
-only within one computer. If you want to use IPC between
+By default, the DDE implementation is used under Windows. DDE works
+within one computer only. If you want to use IPC between
different workstations you should define {\tt
wxUSE\_DDE\_FOR\_IPC} as $0$ before including this header -- this
will force using TCP/IP implementation even under Windows.
exist and will be deleted afterwards) in which case a Unix domain
socket is created.
-{\bf SECURITY NOTE:} Using Internet domain sockets if extremely insecure for
+{\bf SECURITY NOTE:} Using Internet domain sockets is extremely insecure for
IPC as there is absolutely no access control for them, use Unix domain sockets
whenever possible!
\end{verbatim}
Note that it is no longer necessary to call wxDDEInitialize or wxDDECleanUp, since
-wxWidgets will do this itself if necessary.
+wxWidgets will do this by itself if necessary.
\section{Writing non-English applications}\label{nonenglishoverview}
This article describes how to write applications that communicate with
-user in language other than English. Unfortunately many languages use
+the user in a language other than English. Unfortunately many languages use
different charsets under Unix and Windows (and other platforms, to make
-situation even more complicated). These charsets usually differ in so
-many characters it is impossible to use same texts under all platforms.
+the situation even more complicated). These charsets usually differ in so
+many characters that it is impossible to use the same texts under all
+platforms.
-wxWidgets library provides mechanism that helps you avoid distributing many
+The wxWidgets library provides a mechanism that helps you avoid distributing many
identical, only differently encoded, packages with your application
(e.g. help files and menu items in iso8859-13 and windows-1257). Thanks
to this mechanism you can, for example, distribute only iso8859-13 data
Windows).
How is this done? When you tell the wxLocale class to load a message catalog that
-contains correct header, it checks the charset. The catalog is then converted
+contains a correct header, it checks the charset. The catalog is then converted
to the charset used (see
\helpref{wxLocale::GetSystemEncoding}{wxlocalegetsystemencoding} and
\helpref{wxLocale::GetSystemEncodingName}{wxlocalegetsystemencodingname}) by
-user's operating system. This is default behaviour of the
+the user's operating system. This is the default behaviour of the
\helpref{wxLocale}{wxlocale} class; you can disable it by {\bf not} passing
{\tt wxLOCALE\_CONV\_ENCODING} to \helpref{wxLocale::Init}{wxlocaleinit}.
You may want to store all program data (created documents etc.) in
the same encoding, let's say {\tt utf-8}. You can use
-\helpref{wxCSConv}{wxcsconv} class to convert data to encoding used by the
+\helpref{wxCSConv}{wxcsconv} class to convert data to the encoding used by the
system your application is running on (see
\helpref{wxLocale::GetSystemEncoding}{wxlocalegetsystemencoding}).
\wxheading{Help files}
If you're using \helpref{wxHtmlHelpController}{wxhtmlhelpcontroller} there is
-no problem at all. You must only make sure that all the HTML files contain
+no problem at all. You only need to make sure that all the HTML files contain
the META tag, e.g.
\begin{verbatim}
Most C++ GUI frameworks overcome these limitations by means of a set of
macros and functions and wxWidgets is no exception. As it originated before the
-addition of RTTI to the standard C++ and as support for it still missing from
+addition of RTTI to standard C++ and as support for it is still missing from
some (albeit old) compilers, wxWidgets doesn't (yet) use it, but provides its
own macro-based RTTI system.
In the future, the standard C++ RTTI will be used though and you're encouraged
-to use whenever possible \helpref{wxDynamicCast()}{wxdynamiccast} macro which,
+to use whenever possible the \helpref{wxDynamicCast()}{wxdynamiccast} macro which,
for the implementations that support it, is defined just as dynamic\_cast<> and
uses wxWidgets RTTI for all the others. This macro is limited to wxWidgets
classes only and only works with pointers (unlike the real dynamic\_cast<> which
also accepts references).
-Each class that you wish to be known the type system should have
+Each class that you wish to be known to the type system should have
a macro such as DECLARE\_DYNAMIC\_CLASS just inside the class declaration.
The macro IMPLEMENT\_DYNAMIC\_CLASS should be in the implementation file.
Note that these are entirely optional; use them if you wish to check object
The function \helpref{wxCreateDynamicObject}{wxcreatedynamicobject} can be used
to construct a new object of a given type, by supplying a string name.
If you have a pointer to the wxClassInfo object instead, then you
-can simply call wxClassInfo::CreateObject.
+can simply call \helpref{wxClassInfo::CreateObject}{wxclassinfocreateobject}.
\subsection{wxClassInfo}\label{wxclassinfooverview}
\subsection{Checklist sample}\label{samplechecklist}
-This sample demonstrates the use of the \helpref{wxCheckListBox}{wxchecklistbox}
-class intercepting check, select and double click events. It also tests the
+This sample demonstrates use of the \helpref{wxCheckListBox}{wxchecklistbox}
+class intercepting check, select and double click events. It also tests
use of various methods modifying the control, such as by deleting items
from it or inserting new ones (these functions are actually implemented in
the parent class \helpref{wxListBox}{wxlistbox} so the sample tests that class
\subsection{Dialup sample}\label{sampledialup}
This sample shows the \helpref{wxDialUpManager}{wxdialupmanager}
-class. It displays in the status bar the information gathered through its
+class. In the status bar, it displays the information gathered through its
interface: in particular, the current connection status (online or offline) and
whether the connection is permanent (in which case a string `LAN' appears in
the third status bar field - but note that you may be on a LAN not
\subsection{Dynamic sample}\label{sampledynamic}
-This sample is a very small sample that demonstrates the use of the
+This sample is a very small sample that demonstrates use of the
\helpref{wxEvtHandler::Connect}{wxevthandlerconnect} method. This method
should be used whenever it is not known at compile time which control
will receive which event or which controls are actually going to be in
The event sample demonstrates various features of the wxWidgets events. It
shows using dynamic events and connecting/disconnecting the event handlers
-during the run time and also using
+during run time and also using
\helpref{PushEventHandler()}{wxwindowpusheventhandler} and
\helpref{PopEventHandler()}{wxwindowpopeventhandler}.
\subsection{Image sample}\label{sampleimage}
-The image sample demonstrates the use of the \helpref{wxImage}{wximage} class
+The image sample demonstrates use of the \helpref{wxImage}{wximage} class
and shows how to download images in a variety of formats, currently PNG, GIF,
TIFF, JPEG, BMP, PNM and PCX. The top of the sample shows two rectangles, one
of which is drawn directly in the window, the other one is drawn into a
The not very clearly named internat sample demonstrates the wxWidgets
internationalization (i18n for short from now on) features. To be more
precise, it only shows localization support, i.e. support for translating the
-program messages in another language while true i18n would also involve
+program messages into another language while true i18n would also involve
changing the other aspects of the programs behaviour.
More information about this sample can be found in the {\tt readme.txt} file in
\subsection{Scroll subwindow sample}\label{samplescrollsub}
-This sample demonstrates the use of the \helpref{wxScrolledWindow}{wxscrolledwindow}
+This sample demonstrates use of the \helpref{wxScrolledWindow}{wxscrolledwindow}
class including placing subwindows into it and drawing simple graphics. It uses the
\helpref{SetTargetWindow}{wxscrolledwindowsettargetwindow} method and thus the effect
of scrolling does not show in the scrolled window itself, but in one of its subwindows.
The server binds to the local address, using TCP port number 3000,
sets up an event handler to be notified of incoming connection requests
({\bf wxSOCKET\_CONNECTION} events), and sits there, waiting for clients
-({\it listening} in the socket parlance). For each accepted connection,
+({\it listening}, in socket parlance). For each accepted connection,
a new \helpref{wxSocketBase}{wxsocketbase} object is created. These
socket objects are independent from the server that created them, so
they set up their own event handler, and then request to be notified
\subsection{Thread sample}\label{samplethread}
-This sample demonstrates the use of threads in connection with GUI programs.
+This sample demonstrates use of threads in connection with GUI programs.
There are two fundamentally different ways to use threads in GUI programs and
either way has to take care of the fact that the GUI library itself usually
is not multi-threading safe, i.e. that it might crash if two threads try to
\subsection{Treectrl sample}\label{sampletreectrl}
-This sample demonstrates using \helpref{wxTreeCtrl}{wxtreectrl} class. Here
+This sample demonstrates using the \helpref{wxTreeCtrl}{wxtreectrl} class. Here
you may see how to process various notification messages sent by this control
and also when they occur (by looking at the messages in the text control in
the bottom part of the frame).
\subsection{Wizard sample}\label{samplewizard}
-This sample shows so-called wizard dialog (implemented using
+This sample shows the so-called wizard dialog (implemented using
\helpref{wxWizard}{wxwizard} and related classes). It shows almost all
features supported:
\section{Window styles}\label{windowstyles}
Window styles are used to specify alternative behaviour and appearances for windows, when they are
-created. The symbols are defined in such as way that they can be combined in a `bit-list' using the
+created. The symbols are defined in such a way that they can be combined in a `bit-list' using the
C++ {\it bitwise-or} operator. For example:
\begin{verbatim}
projects / wxWidgets.git / commitdiff
