\documentstyle[a4,makeidx,verbatim,texhelp,fancyhea,mysober,mytitle]{report}
% This is for dvi2tty only
%\setlength{\textwidth}{12 true cm}    % shorten line length
%\renewcommand{\baselinestretch}{.5}   % singlespacing
%
\input psbox.tex
\parskip=10pt
\parindent=0pt
\title{wxWindows Frequently Asked Questions Version 1.2}
\author{Julian Smart and others}
\date{October 1994}
\makeindex
\begin{document}
\maketitle
\pagestyle{fancyplain}
\bibliographystyle{plain}
\setheader{{\it CONTENTS}}{}{}{}{}{{\it CONTENTS}}
\setfooter{\thepage}{}{}{}{}{\thepage}%
\pagenumbering{roman}
\tableofcontents
%
\chapter{About this document}
\setheader{{\it FAQ}}{}{}{}{}{{\it FAQ}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

This is the questions-and-answers document for wxWindows, the free multi-platform
GUI C++ library. Please feel free to comment on this FAQ and submit new entries.

\chapter{General questions}

\section{What are the licensing considerations for wxWindows?}

None. You may make any use of any part of wxWindows, and no payment is
necessary. While it's nice if you acknowledge the author(s) of wxWindows
in your own work, it's not necessary.

Correspondingly, there is no warranty with wxWindows, as you have probably
guessed by now.

\section{Why is wxWindows free, and will it ever be shareware?}

It's free because:

\begin{itemize}
\item it was never intended to compete as a commercial product, since
there are not sufficient resources at AIAI
\item the feedback and bug fixes that AIAI get from the Internet community
are extremely valuable
\item having used much free software in the past, it's only right
to put something back
\item AIAI gains a small amount of publicity (well, so the story goes)
\item I got bored of writing code that never saw the light of day
\end{itemize}

I have no plans to produce a shareware version. Perhaps someone
will produce a value-added shareware version (in the same manner that
the once-free image viewer {\it XV} uses much freely-contributed code), but it won't
be me.

\section{Why the silly name?}

{\bf w} for MS Windows, {\bf x} for the X windowing system, Windows for those rectangular
things you see a lot of. Ok, so it's not exactly inspired.

\section{Are there any GIF/BMP loading facilities for wxWindows?}

There is Windows .BMP code that compiles under Windows distributed
with wxWindows 1.50k (utils/dib directory). wxWindows 1.60 will allow
proper colourmap setting with this code.

For X, an archive called image.tar.gz in /pub/wxwin/contrib contains
code to load GIFS, Windows bitmaps and X bitmaps into a canvas
(and optionally, a wxBitmap). The code has been taken from
a pre-shareware version of the excellent image viewer XV;
it cannot be guaranteed that the code is free from copyright
issues.  See the file test.cc for a scanty explanation of how
to use it.

\chapter{Compilation issues}

\section{Linux issues}

\subsection{Why do the makefiles not work?}

You may be using `pmake': the wxWindows makefiles
require you to be using the default GNU make, which has
a slightly different syntax (for example, the include
statement syntax is different).

\subsection{My binaries are enormous! What can I do?}

wxWindows 1.60 improves on 1.50 by the use of GCC pragmas to
specify which files are interfaces and which are implementation.

Also, if you compile everything without debugging information,
GCC will use dynamic link libraries for X11, XView and some others;
this reduces the size of the binary substantially.

You can also create a dynamic version of wx\_ol.lib; see
the files in the /pub/wxwin/contrib area which help
create a dynamic library, and also the notes in /usr/doc/faq.

See also install.txt for a discussion of these issues.

\subsection{Why does the Xfree ATI Mach32 server hang when drawing
graphics?}

Harri Pasanen has discovered a bug in the Mach32 server.
It hangs if using pens with wxDOT linestyle, and width zero.

This has been reported to the Xfree developers.

\section{Solaris 2.x issues}

\subsection{I get some warnings and link errors. What gives?}

You need to:

\begin{itemize}
\item Compile with -DSVR4. Add this to OPTIONS line in each
makefile.unx.
\item Add the following to LDFLAGS: -lgen -ldl -lsocket -lnsl
\end{itemize}

Note that the libgen.a lives in /usr/ccs/lib, if you
have installed the programming tools option.

Version 4.0 of Sun C++ is apparently more pedantic than
older versions, and requires the use of CC -migration to
help with the necessary changes.

Someone reported that link errors on a SPARCStation were
cured by adding -lucb and -I/usr/ucbinclude/sys.

For dynamic linking under Solaris 2.3, the following
changes are required:

\begin{itemize}
\item In wxinstal, add:

\begin{verbatim}
export OPTIONS
OPTIONS=-fPIC
\end{verbatim}%
\item in src/x/makefile.unx, add:

\begin{verbatim}
WXLIB = $(WXDIR)/lib/libwx$(GUISUFFIX).so.0

$(WXLIB): $(OBJECTS) $(BASEOBJECTS)
      	ld -G -o $(WXLIB) $(OBJECTS) $(BASEOBJECTS)
\end{verbatim}

where the ld line replaces the ar+ranlib command.
\end{itemize}

\section{How can I use wxWindows with Borland C++?}

\subsection{To create new IDE project files}

\begin{enumerate}
\item The IDE must recognize .cc files to edit and compile wxWindows
source. You must add .cc to the extension lists in the
Options/Tools/CppCompile, Options/Tools/EditText and
Options/Environment/Syntax Highlighting menus.
\item Create a new project file with the following settings:
\begin{itemize}
\item Platform: Win16 or Win32 (always the same)
\item Standard libs: No OWL, no Class Lib (not portables)
\item Advanced Ops/(the sources already exist? Off everything: No source node)
\end{itemize}
\item If the source files already exist, just type Ins on the target name
(*.exe or *.lib) of the project window. The selector file dialog must
appear. Then select all the relevant *.cc files, and the *.rc and 
*.def files. 

If you are not sure about wich files must be included, look into a
makefile, if it exists, for the sources. Don't worry about libraries,
BC4 has its own windows libraries.
\end{enumerate}

\subsection{To use old *.prj project files}

The IDE can read version 3.1 *.prj files, and then convert them to the
new format. You must repeat item 1 (above) each time you read
a *.prj file, and sometimes you'll have to select the .cc files in 
the project window, and drop them on the target file (.exe or .lib), 
in order to obtain little bullets in left of the project window 
(ie. to make the IDE recognize the files). If there are no many .cc 
files, I recomend to create a new *.ide file.

\subsection{To use makefiles}

See the /pub/wxwin/contrib directory for Borland makefiles (bormake.zip).
If this doesn't work for you, create a new IDE file, and then 
click Project/Generate\_Makefile.

\subsection{To compile wxWindows projects}

\begin{enumerate}
\item Set the proper directories. In Options/Project/Directories/Include,
add \verb$"(wxdir)\include\base;(wxdir)\include\msw"$, where (wxdir) must be
changed for the wxWindows base directory. Avoid absolute paths 
in your code, if you want it to be portable. 
\item Check Options/Messages/Selected and in this menu uncheck
Potential C++ errors/"function f1 hides virtual function f2", to reduce
the amount of message warnings during compiling.
\item A typical Windows application (16bits mode) can't have a data segment
larger than 64k. To use far data, you must check "Automatic far data"
and reduce the threshold. Read install notes, and see
\rtfsp\helpref{Data segment overflow}{dataseg}
\end{enumerate}

\hrule
{\it Contributed by Aguilar Sierra Alejandro-CCA \verb$<asierra@mx.unam.dgsca.redvax1>$}

\section{Why do I get "data segment overflow error" when linking using Borland compiler?}\label{dataseg}

You have a number of switches in compiler configuration that may need
adjusting. In order of my own preference:

\begin{enumerate}
\item Make sure that stack is located in a different segment from data.
     It saves you about 16k.

IDE:
\begin{itemize}
\item "Assume DS==SS" - Never, Never and Never! 
\item "Smart callbacks" -Off.
\end{itemize}

Command line:
\begin{itemize}
\item -WE -Fs-
\end{itemize}

DrawBacks: All functions that are exported to Windows must be 
explicitly declared so, and MakeProcInstance() call is neccessary.
(This is done in wxWin, just take care of your own callbacks).

For version 150k you have to uncomment one MakeProcInstance() in
src/msw/wx\_main.c (or wx\_win.c - don't remember exactly). 
The patch is sent to Julian.
   
\item Put virtual tables into code segment.
It saves you 4bytes*per\_virtual\_function\_per\_class. Inherited functions
also count. Result is more than you can expect. 

IDE:
\begin{itemize}
\item "Far virtual tables" - On.
\end{itemize}

Command line: 
\begin{itemize}
\item -Vf
\end{itemize}

Drawbacks: All C++ libraries and objects must be compiled with the
same settings of this switch or you'll get "undefined symbol" link
errors. Put this is in your default configuration file and 
recompile everything to save yourself from trouble later.
\item Turn on automatic far data.

IDE:
\begin{itemize}
\item "Automatic far data" - On,
\item "Far data threshold" - 4.
\end{itemize}

Command line:
\begin{itemize}
\item -Ff=4
\end{itemize}

Drawbacks: you can't run more than one instance of your program
anymore. This is architectural flaw in MS-Windows. If you need to,
make several copies of your .exe under different names and run 
one copy of each.
\item Put constant strings in code segments.

IDE:
\begin{itemize}
\item "Put constant strings in code segments"
\end{itemize}

Command line:
\begin{itemize}
\item -dc
\end{itemize}

Drawbacks: Not available with Borland 3.1. 
You probably wan't be able to modify any of these strings, since
they are in code segments. If windows does not prohibit write
access to code segments, then this will cause hard to find bugs.
(Code segments are marked as discardable and can be thrown away and
reloaded from .exe file at any moment).
(I did not tried it myself yet).
\end{enumerate}

\hrule
{\it Contributed by Alexei Vovenko \verb$<alv@au.edu.dstc>$}

\section{Is it possible to use multithreaded library with wxWindows under MS-Windows?}

Yes, if you do it carefully. First of all make sure that your
compiler does not make any unreasonable assumptions about stack
segment, and better still it makes no assumptions about stack segment
at all. Make sure that both the library and your program are compiled 
this way. 

Do not expect wxWindows to be reentrant because MS-Windows is not.   
Most probably your thread implementation does not use preemptive scheduler,
so MS-Windows reentrancy is not a big problem.

Derive your member from "Bool wxApp::OnIdle(void)" 
and put a pthread\_yield() call there. If you use dialogs, take care about
yielding to threads while in a dialog.

\hrule
{\it Contributed by Alexei Vovenko \verb$<alv@au.edu.dstc>$}

\section{Can I use wxWindows with Watcom C++?}

People are working on Watcom support; watch this space. So far, however,
it seems that only 16-bit wxWindows programs will compile with Watcom
due to a bug in the compiler.

\section{How can I compile PROLOGIO with Borland C++?}

Borland users have been finding that it's impossible to compile
the LEX and YACC-generated parser files in PROLOGIO from wxWindows
1.50. PROLOGIO is required for compiling wxBuilder.

Peter Trattler and Edward Zimmermann have improved PROLOGIO to allow
FLEX to be optionally used instead of LEX; see the PROLOGIO manual for
more details. If you have FLEX (the default Linux lexical analyser
generator), you can generate a lex\_yy.c which compiles more cleanly.

LEX and FLEX-generated versions of lex\_yy.c are supplied, as
lexyy.c and flexyy.c respectively.

FLEX and YACC are freely available for DOS; most major DOS ftp
sites should have them.

\section{I get a compilation error in wb\_item.cc using Borland C++.}

In release 1.50 k there's a bug: edit wb\_item.cc, go down
to the wxbRadioBox constructor and replace

\begin{verbatim}
#ifndef _turboc
\end{verbatim}

with 

\begin{verbatim}
#ifndef __BORLANDC__
\end{verbatim}

\section{Can I use DJGPP with wxWindows?}

Unfortunately not, at present. There is a toolkit called RSXDK which
allows limited 32-bit Windows compilation under Windows 3.0 using
DJGPP, but it has not yet been ported to use the Windows 3.1 header
fle. I've tried it, but had link errors. I mailed the author of
RSXDK but no replies yet (JACS).

If anyone wants to try getting DJGPP and RSXDK to work with Windows 3.1,
and then with wxWindows, they are very welcome.

\chapter{C++ issues}

\section{How can I have class member functions as callbacks
for buttons?}

Here's some correspondence on the subject.

\verbatiminput{members.txt}
%
\section{How can I display debugging messages?}

If you use the function wxDebugMsg, messages will be displayed on either
the standard error stream (X) or the debugging stream (Windows). To read
these messages under Windows, you must either be running a debugger,
or (perhaps more convenient), using a program such as Microsoft's DBWIN
which displays these debugging messages in a text window.

Using DBWIN on a regular basis has the advantage of showing up some GDI
errors that you might otherwise miss, but that could cause severe
problems in future. DBWIN is available in the Windows SDK or
on the Developer's Network CD-ROM, and probably by ftp from Microsoft's
site.

\chapter{Platforms}

\section{Is there a Mac version of wxWindows under development?}

Bill Hale \verb$<hale@edu.tulane.tcs.mailhost>$ is working on this. Here's
his response to a recent email on the subject:

\begin{verbatim}
I have been working on the Macintosh version of wxWindows since June [1994].

The Macintosh version handles most of the methods for wxFrame, wxPanel,
wxCanvas. It also handles wxMenu, wxMenuBar, wxMenuItem, and wxCheckBox.
The wxCanvasDC can draw point, line, and rectangle.

For the first release version, I don't intend to do wxSlider, wxTimer,
wxPathList, wxClient, wxConnection, wxPostScriptDC, wxMetaFileDC,
wxForm, wxHelpInstance, wxMetaFile, wxServer. Some methods in other
classes may also not be implemented.

I'm trying to get a working version that does most of the standard
functions. Then, I will upload it so that we can discuss what changes
are necessary to make it conform with the guidelines for wxWindows.

I hope to have something ready by the beginning of September [1994], at least
for discussion purposes.
\end{verbatim}

\section{Is there an X version of wxBuilder?}

Sort of... the XView version needs some work, particularly because there
are occasions when 2 levels of modal dialogs are used, which XView doesn't
like.

The Motif version is coming on well and will be released (a binary for Suns and HPs)
by the end of September.

\chapter{Run-time problems}

\section{Why does my program exit abnormally with initializing?}

You may be declaring a pen, brush, icon, cursor or colour globally.
These objects automatically add themselves to global lists which may
not be initialized before the object constructors are called, and so
only global pointers to these objects may be declared. After or during
\rtfsp{\bf OnInit} is called, these objects may be created with impunity.

\section{After using memory DCs and bitmaps under Windows, I get system crashes.}

Here's some correspondence that helps explain this phenomenon and its
solution.

\begin{verbatim}
From: Markus Meisinger <Markus.Meisinger@at.ac.uni-linz.risc>
Message-Id: <199406241203.AA09143@melmac.risc.uni-linz.ac.at>
To: wxwin-users@ed.aiai
Subject: SOLUTION to strange problems of yesterday
Status: RO

hi wxWindows programers

i wrote yesterday:

>I have encountered some strange problems with the sample programs under
>MS-WINDOWS 3.11. (they work fine under UNIX/LINUX)
>
>The problems arise if i e.g quit the minimal sample program. During the run
>of the program no problems appear. But after it stops than the whole
>system crashes (not always, but quite often :)!
>
>If the system crashes, not only the sample program produces an
>UNRECOVERABLE APPLICATION ERROR, but also the most other programs running
>at the same time (PROGMAN, FILEMAN, WINMETER, ...) stop their work with
>a severe error. :(
>
>Any help would be greatly appreciated! Or is there a patch available, because
>a guess their is a bug in freeing the system resources ...

The actual problem causing the strange behaviour was a buggy wxWindows program
of mine running some minutes before and not the sample programs, CTL3D or
FAFALIB

Because i used a wxMemoryDC in which i selected a dynamicaly created bitmap.
During the quiting process i freed this bitmap which was selected in the
wxMemoryDC. But wxWindows also freed this bitmap during deleting the DC and
... the rest you know

SO, BE AWARE IF YOU DELETE BITMAPS! 

Never delete a bitmap which is selected into a DC if the DC will be deleted.
The bitmap will be deleted by the DC!
But i did it !!! :) and it resulted in a system wide crash of MS-WINDOWS
(in Motif it works fine (why?))
The funny thing with this crash is that the system doesn't immediately crash,
instead it works fine for a few minutes until ANY other program gets into
some memory conflict. After this application error each program still running
complains problems with the memory and stops. The last thing you see is
the standard windows background color (if you are lucky:)
I never saw such a system wide crash WOU :) in some sense it was funny :)

Hope you don't make the same errors as i did!

Markus
\end{verbatim}

\section{Why do panel items not size or position correctly under Motif?}

Absolute positioning in Motif doesn't mix well with constraint-based positioning,
as used by wxWindows to implement left-to-right, top-to-bottom layout.

If you know that all your widgets are going to be positioned and sized explicitly,
you should pass the style flag {\bf wxABSOLUTE\_POSITIONING} to the panel constructor,
in which case a Motif bulletin board widget will be used instead of a form widget.

{\it NOTE:} from wxWindows 1.60, the wxABSOLUTE\_POSITIONING flag is
obsolete, because all Motif positioning is now done this way.

One reason for a widget not appearing can be that the widget
is sized just too big for the panel, and then Motif gets very
confused. Try reducing the size of the widget.

Another possibility is to try setting the widget sizes first, and
finally setting the panel size.

\section{Under Windows, dialog boxes refuse to appear. Why?}

You probably forgot to include the file wx.rc in your resource script
This is required for dialog boxes to work correctly.

\section{Under XView, I get a SERVER\_IMAGE\_BITMAP\_FILE warning mesage.}

{\tt XView warning: SERVER\_IMAGE\_BITMAP\_FILE: Server image creation failed (Server Image package)}

The application may be looking for an icon file which does not exist or
has been referenced by a relative icon pathname. Use an absolute path, or
include the icon image in the source file using conditional compilation
(see the reference manual's {\bf wxIcon} class entry).

\section{Under Windows, MDI child windows don't size properly.}

For some reason, it's not possible to programmatically resize an MDI
child frame just after creation, so using {\it Fit} to size an MDI
child frame around a subwindow does not work.

Also, it does not seem to be possible (on creation at least) to hide an
MDI child frame, resize its subwindows, then show it.

If you are using {\it Fit} to size the child window, you must
put up with seeing the windows repaint themselves: the child
window will come up already visible.

However, if you know the size of the window in advance, give it an
absolute size, create it with the wxMINIMIZE window style, draw
the contents, then call {\it Iconize(FALSE)} to restore the
window. This at least avoids seeing half-painted windows whilst
things get initialized.

\section{Functions that return string values cause strange behaviour
on some platforms.}

To resolve the question of who is responsible for allocating and
deallocating memory, wxWindows maintains a policy (unless
documented otherwise) of returning a {\it temporary} pointer
to a static string buffer from functions such as {\it wxText::GetValue}.

If you don't immediately take a copy of this value, it's possible that
subsequent wxWindows calls will use the same memory, causing
unpredictable results. This tends to be more the case under Windows than
other platforms, where pointers to internal XView or Motif widget
strings are often returned.

\begin{comment}
\begin{helpglossary}
\setheader{{\it GLOSSARY}}{}{}{}{}{{\it GLOSSARY}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

\gloss{API}

Application Programmer's Interface - a set of calls and classes defining
how a library (in this case, wxWindows) can be used.

\gloss{Canvas}

A canvas in XView and wxWindows is a subwindow on which graphics (but
not panel items) can be drawn. It may be scrollable. A canvas has a
{\it device context}\/ associated with it.

\gloss{DDE}

Dynamic Data Exchange - Microsoft's interprocess communication protocol.
wxWindows provides an abstraction of DDE under both Windows and UNIX.

\gloss{Device context}

A device context is an abstraction away from devices such as windows,
printers and files. Code that draws to a device context is generic since
that device context could be associated with a number of different real
device. A canvas has a device context, although duplicate graphics calls
are provided for the canvas, so the beginner doesn't have to think in
terms of device contexts when starting out. wxWindows supports device
contexts for canvas, Windows printer, and Encapsulated PostScript files on UNIX.

\gloss{Dialog box}

In wxWindows a dialog box is a convenient way of popping up a window
with panel items, without having to explicitly create a frame and a
panel. A dialog box may be modal or modeless. A modal dialog does not
return control back to the calling program until the user has dismissed
it, and all other windows in the application are disabled until the
dialog is dismissed.  A modeless dialog is just like a normal window in
that the user can access other windows while the dialog is displayed.

\gloss{Frame}

Under XView (and wxWindows), a visible window usually consists of a
frame which contains zero or more subwindows, such as text subwindow,
canvas, and panel. Under Windows 3, windows can be nested arbitrarily,
but this is not currently supported in wxWindows.

\gloss{GNU C++}

A free, solid C++ compiler which may be used to compile the UNIX side of
wxWindows applications.

\gloss{GUI}

Graphical User Interface, such as Windows 3 or X.

\gloss{Menu bar}

A menu bar is a series of labelled menus, usually placed near the top
of a window. It is popular in Windows 3 and Motif applications, and as
such is a supported feature, but wxWindows has to `simulate' the menu
bar under XView by using a panel and several menu buttons.

\gloss{Metafile}

Microsoft Windows-specific object which may contain a restricted set of
GDI primitives. It is device independent, since it may be scaled without
losing precision, unlike a bitmap. A metafile may exist in a file or in
memory. wxWindows implements enough metafile functionality to use it to
pass graphics to other applications via the clipboard.

\gloss{Open Look}

A specification for a GUI `look and feel', initiated by Sun
Microsystems. XView is one toolkit for writing Open Look applications
under X, and wxWindows sits on top of XView.

\gloss{Panel}

A panel in XView and wxWindows terminology is a subwindow on which a
limited range of panel items (widgets or controls for user input) can be
placed. wxWindows allows panel items to be placed explicitly, or laid
out from left to right, top to bottom, which is a more platform
independent method since spacing is calculated automatically at run time.
Panel items cannot be placed on a canvas, which is specifically for
drawing graphics.

\gloss{RPC}

Remote Procedure Call - a method of interprocess communication akin to
procedure call, where the client process makes a call to a server, which
sends back a result. The AIAI-supplied PROLOGIO library supports a
simple RPC protocol based on DDE (but working under both UNIX and
Windows).

\gloss{Status line}

A status line is often found at the base of a window, to keep the user
informed (for instance, giving a line of description to menu items, as in the
{\bf hello} demo). XView has a status line (or footer) capability, but
wxWindows implements the feature explicitly under Windows 3 and Motif.

\gloss{Text subwindow}

In XView and Motif, a text subwindow is supplied for displaying and
retrieving text from a window. It has a rich set of features, only a
small subset of which is currently catered for by wxWindows.

\gloss{XView}

An X toolkit supplied by Sun Microsystems, initially just for porting
SunView applications to X, but which has become a popular toolkit in its
own right due to its simplicity of use. XView implements Sun's Open Look
`look and feel' for X, but is not the only toolkit to do so.

\end{helpglossary}
\end{comment}
\newpage
\addcontentsline{toc}{chapter}{Index}
\printindex
\end{document}
