From 42b3e73ede6a1c45b0df4a9a29c92f952b8b03c2 Mon Sep 17 00:00:00 2001 From: Julian Smart Date: Thu, 23 Nov 2000 20:33:40 +0000 Subject: [PATCH] Some mods git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@8778 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/latex/book/chap_basic_events.tex | 348 ++++++++++++++++++- docs/latex/book/chap_install.tex | 459 +++++++++++++++++++++++++- docs/latex/book/chap_intro.tex | 2 +- docs/latex/book/makefile.vc | 2 +- docs/latex/book/tex2rtf.ini | 6 +- 5 files changed, 812 insertions(+), 5 deletions(-) diff --git a/docs/latex/book/chap_basic_events.tex b/docs/latex/book/chap_basic_events.tex index f4ef86d94d..dfa56b2b77 100644 --- a/docs/latex/book/chap_basic_events.tex +++ b/docs/latex/book/chap_basic_events.tex @@ -3,5 +3,351 @@ \setheader{{\it CHAPTER \thechapter: BASIC EVENT HANDLING}}{}{}{}{}{{\it CHAPTER \thechapter: BASIC EVENT HANDLING}}% \setfooter{\thepage}{}{}{}{}{\thepage}% -In which Pooh and Piglet come upon the sticky topic of event handling, and ask Owl to help. +\section{Introduction} + +In most cases, wxWindows uses the concept of {\it event tables} to catch user input. + +An event table is placed in an implementation file to tell wxWindows how to map +events to member functions. These member functions are not virtual functions, but +they are all similar in form: they take a single wxEvent-derived argument, and have a void return +type. + +Here's an example of an event table. + +\begin{verbatim} +BEGIN_EVENT_TABLE(MyFrame, wxFrame) + EVT_MENU (wxID_EXIT, MyFrame::OnExit) + EVT_MENU (DO_TEST, MyFrame::DoTest) + EVT_SIZE ( MyFrame::OnSize) + EVT_BUTTON (BUTTON1, MyFrame::OnButton1) +END_EVENT_TABLE() +\end{verbatim} + +The first two entries map menu commands to two different member functions. The EVT\_SIZE macro +doesn't need a window identifier, since normally you are only interested in the +current window's size events. (In fact you could intercept a particular window's size event +by using EVT\_CUSTOM(wxEVT\_SIZE, id, func).) + +The EVT\_BUTTON macro demonstrates that the originating event does not have to come from +the window class implementing the event table - if the event source is a button within a panel within a frame, this will still +work, because event tables are searched up through the hierarchy of windows. In this +case, the button's event table will be searched, then the parent panel's, then the frame's. + +As mentioned before, the member functions that handle events do not have to be virtual. +Indeed, the member functions should not be virtual as the event handler ignores that +the functions are virtual, i.e. overriding a virtual member function in a derived class +will not have any effect. +These member functions take an event argument, and the class of event differs according +to the type of event and the class of the originating window. For size +events, \wxhelpref{wxSizeEvent}{wxsizeevent} is used. For menu commands and most control +commands (such as button presses), \wxhelpref{wxCommandEvent}{wxcommandevent} is used. +When controls get more complicated, then specific event classes are used, such +as \wxhelpref{wxTreeEvent}{wxtreeevent} for events from \wxhelpref{wxTreeCtrl}{wxtreectrl} windows. + +As well as the event table in the implementation file, there must be a DECLARE\_EVENT\_TABLE +macro in the class definition. For example: + +{\small% +\begin{verbatim} +class MyFrame: public wxFrame { + + DECLARE_DYNAMIC_CLASS(MyFrame) + +public: + ... + void OnExit(wxCommandEvent& event); + void OnSize(wxSizeEvent& event); +protected: + int m_count; + ... + DECLARE_EVENT_TABLE() +}; +\end{verbatim} +}% + +\section{How events are processed}\label{eventprocessing} + +When an event is received from the windowing system, wxWindows calls \wxhelpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent} on +the first event handler object belonging to the window generating the event. + +It may be noted that wxWindows' event processing system implements something +very close to virtual methods in normal C++, i.e. it is possible to alter +the behaviour of a class by overriding its event handling functions. In +many cases this works even for changing the behaviour of native controls. +For example it is possible to filter out a number of key events sent by the +system to a native text control by overriding wxTextCtrl and defining a +handler for key events using EVT\_KEY\_DOWN. This would indeed prevent +any key events from being sent to the native control - which might not be +what is desired. In this case the event handler function has to call Skip() +so as to indicate that the search for the event handler should continue. + +To summarize, instead of explicitly calling the base class version as you +would have done with C++ virtual functions (i.e. {\it wxTextCtrl::OnChar()}), +you should instead call \wxhelpref{wxEvent::Skip}{wxeventskip}. + +In practice, this would look like the following if the derived text control only +accepts 'a' to 'z' and 'A' to 'Z': + +{\small% +\begin{verbatim} +void MyTextCtrl::OnChar(wxKeyEvent& event) +{ + if ( isalpha( event.KeyCode() ) ) + { + // key code is within legal range. we call event.Skip() so the + // event can be processed either in the base wxWindows class + // or the native control. + + event.Skip(); + } + else + { + // illegal key hit. we don't call event.Skip() so the + // event is not processed anywhere else. + + wxBell(); + } +} +\end{verbatim} +}% + + +The normal order of event table searching by ProcessEvent is as follows: + +\begin{enumerate}\itemsep=0pt +\item If the object is disabled (via a call to \wxhelpref{wxEvtHandler::SetEvtHandlerEnabled}{wxevthandlersetevthandlerenabled}) +the function skips to step (6). +\item If the object is a wxWindow, {\bf ProcessEvent} is recursively called on the window's\rtfsp +\wxhelpref{wxValidator}{wxvalidator}. If this returns TRUE, the function exits. +\item {\bf SearchEventTable} is called for this event handler. If this fails, the base +class table is tried, and so on until no more tables exist or an appropriate function was found, +in which case the function exits. +\item The search is applied down the entire chain of event handlers (usually the chain has a length +of one). If this succeeds, the function exits. +\item If the object is a wxWindow and the event is a wxCommandEvent, {\bf ProcessEvent} is +recursively applied to the parent window's event handler. If this returns TRUE, the function exits. +\item Finally, {\bf ProcessEvent} is called on the wxApp object. +\end{enumerate} + +{\bf Pay close attention to Step 5.} People often overlook or get +confused by this powerful feature of the wxWindows event processing +system. To put it a different way, events derived either directly or +indirectly from wxCommandEvent will travel up the containment +hierarchy from child to parent until an event handler is found that +doesn't call event.Skip(). Events not derived from wxCommandEvent are +sent only to the window they occurred in and then stop. + +Typically events that deal with a window as a window (size, motion, +paint, mouse, keyboard, etc.) are sent only to the window. Events +that have a higher level of meaning and/or are generated by the window +itself, (button click, menu select, tree expand, etc.) are command +events and are sent up to the parent to see if it is interested in the +event. + +Note that your application may wish to override ProcessEvent to redirect processing of +events. This is done in the document/view framework, for example, to allow event handlers +to be defined in the document or view. To test for command events (which will probably +be the only events you wish to redirect), you may use wxEvent::IsCommandEvent for +efficiency, instead of using the slower run-time type system. + +As mentioned above, only command events are recursively applied to the parents event +handler. As this quite often causes confusion for users, here is a list of system +events which will {\it not} get sent to the parent's event handler: + +\begin{twocollist}\itemsep=0pt +\twocolitem{\wxhelpref{wxEvent}{wxevent}}{The event base class} +\twocolitem{\wxhelpref{wxActivateEvent}{wxactivateevent}}{A window or application activation event} +\twocolitem{\wxhelpref{wxCloseEvent}{wxcloseevent}}{A close window or end session event} +\twocolitem{\wxhelpref{wxEraseEvent}{wxeraseevent}}{An erase background event} +\twocolitem{\wxhelpref{wxFocusEvent}{wxfocusevent}}{A window focus event} +\twocolitem{\wxhelpref{wxKeyEvent}{wxkeyevent}}{A keypress event} +\twocolitem{\wxhelpref{wxIdleEvent}{wxidleevent}}{An idle event} +\twocolitem{\wxhelpref{wxInitDialogEvent}{wxinitdialogevent}}{A dialog initialisation event} +\twocolitem{\wxhelpref{wxJoystickEvent}{wxjoystickevent}}{A joystick event} +\twocolitem{\wxhelpref{wxMenuEvent}{wxmenuevent}}{A menu event} +\twocolitem{\wxhelpref{wxMouseEvent}{wxmouseevent}}{A mouse event} +\twocolitem{\wxhelpref{wxMoveEvent}{wxmoveevent}}{A move event} +\twocolitem{\wxhelpref{wxPaintEvent}{wxpaintevent}}{A paint event} +\twocolitem{\wxhelpref{wxQueryLayoutInfoEvent}{wxquerylayoutinfoevent}}{Used to query layout information} +\twocolitem{\wxhelpref{wxSizeEvent}{wxsizeevent}}{A size event} +\twocolitem{\wxhelpref{wxScrollWinEvent}{wxscrollwinevent}}{A scroll event sent by a scrolled window (not a scroll bar)} +\twocolitem{\wxhelpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}}{A system colour change event} +\twocolitem{\wxhelpref{wxUpdateUIEvent}{wxupdateuievent}}{A user interface update event} +\end{twocollist} + +In some cases, it might be desired by the programmer to get a certain number +of system events in a parent window, for example all key events sent to, but not +used by, the native controls in a dialog. In this case, a special event handler +will have to be written that will override ProcessEvent() in order to pass +all events (or any selection of them) to the parent window. + +% VZ: it doesn't work like this, but just in case we ever reenable this +% behaviour, I leave it here +% +% \section{Redirection of command events to the window with the focus} +% +% The usual upward search through the window hierarchy for command event +% handlers does not always meet an application's requirements. Say you have two +% wxTextCtrl windows in a frame, plus a toolbar with Cut, Copy and Paste +% buttons. To avoid the need to define event handlers in the frame +% and redirect them explicitly to the window with the focus, command events +% are sent to the window with the focus first, for +% menu and toolbar command and UI update events only. This means that +% each window can handle its own commands and UI updates independently. In +% fact wxTextCtrl can handle Cut, Copy, Paste, Undo and Redo commands and UI update +% requests, so no extra coding is required to support them in your menus and +% toolbars. + +\section{Pluggable event handlers} + +In fact, you don't have to derive a new class from a window class +if you don't want to. You can derive a new class from wxEvtHandler instead, +defining the appropriate event table, and then call +\rtfsp\wxhelpref{wxWindow::SetEventHandler}{wxwindowseteventhandler} (or, preferably, +\rtfsp\wxhelpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler}) to make this +event handler the object that responds to events. This way, you can avoid +a lot of class derivation, and use the same event handler object to +handle events from instances of different classes. If you ever have to call a window's event handler +manually, use the GetEventHandler function to retrieve the window's event handler and use that +to call the member function. By default, GetEventHandler returns a pointer to the window itself +unless an application has redirected event handling using SetEventHandler or PushEventHandler. + +One use of PushEventHandler is to temporarily or permanently change the +behaviour of the GUI. For example, you might want to invoke a dialog editor +in your application that changes aspects of dialog boxes. You can +grab all the input for an existing dialog box, and edit it `in situ', +before restoring its behaviour to normal. So even if the application +has derived new classes to customize behaviour, your utility can indulge +in a spot of body-snatching. It could be a useful technique for on-line +tutorials, too, where you take a user through a serious of steps and +don't want them to diverge from the lesson. Here, you can examine the events +coming from buttons and windows, and if acceptable, pass them through to +the original event handler. Use PushEventHandler/PopEventHandler +to form a chain of event handlers, where each handler processes a different +range of events independently from the other handlers. + +\section{Window identifiers}\label{windowids} + +\index{identifiers}\index{wxID}Window identifiers are integers, and are used to uniquely determine window identity in the +event system (though you can use it for other purposes). In fact, identifiers do not need +to be unique across your entire application just so long as they are unique within a particular context you're interested +in, such as a frame and its children. You may use the wxID\_OK identifier, for example, on +any number of dialogs so long as you don't have several within the same dialog. + +If you pass -1 to a window constructor, an identifier will be generated for you, but beware: +if things don't respond in the way they should, it could be because of an id conflict. It is safer +to supply window ids at all times. Automatic generation of identifiers starts at 1 so may well conflict +with your own identifiers. + +The following standard identifiers are supplied. You can use wxID\_HIGHEST to determine the +number above which it is safe to define your own identifiers. Or, you can use identifiers below +wxID\_LOWEST. + +\begin{verbatim} +#define wxID_LOWEST 4999 + +#define wxID_OPEN 5000 +#define wxID_CLOSE 5001 +#define wxID_NEW 5002 +#define wxID_SAVE 5003 +#define wxID_SAVEAS 5004 +#define wxID_REVERT 5005 +#define wxID_EXIT 5006 +#define wxID_UNDO 5007 +#define wxID_REDO 5008 +#define wxID_HELP 5009 +#define wxID_PRINT 5010 +#define wxID_PRINT_SETUP 5011 +#define wxID_PREVIEW 5012 +#define wxID_ABOUT 5013 +#define wxID_HELP_CONTENTS 5014 +#define wxID_HELP_COMMANDS 5015 +#define wxID_HELP_PROCEDURES 5016 +#define wxID_HELP_CONTEXT 5017 + +#define wxID_CUT 5030 +#define wxID_COPY 5031 +#define wxID_PASTE 5032 +#define wxID_CLEAR 5033 +#define wxID_FIND 5034 +#define wxID_DUPLICATE 5035 +#define wxID_SELECTALL 5036 + +#define wxID_FILE1 5050 +#define wxID_FILE2 5051 +#define wxID_FILE3 5052 +#define wxID_FILE4 5053 +#define wxID_FILE5 5054 +#define wxID_FILE6 5055 +#define wxID_FILE7 5056 +#define wxID_FILE8 5057 +#define wxID_FILE9 5058 + +#define wxID_OK 5100 +#define wxID_CANCEL 5101 +#define wxID_APPLY 5102 +#define wxID_YES 5103 +#define wxID_NO 5104 +#define wxID_STATIC 5105 + +#define wxID_HIGHEST 5999 +\end{verbatim} + +\section{Event macros summary}\label{eventmacros} + +\wxheading{Generic event table macros} + +\twocolwidtha{8cm}% +\begin{twocollist}\itemsep=0pt +\twocolitem{\windowstyle{EVT\_CUSTOM(event, id, func)}}{Allows you to add a custom event table +entry by specifying the event identifier (such as wxEVT\_SIZE), the window identifier, +and a member function to call.} +\twocolitem{\windowstyle{EVT\_CUSTOM\_RANGE(event, id1, id2, func)}}{The same as EVT\_CUSTOM, +but responds to a range of window identifiers.} +\twocolitem{\windowstyle{EVT\_COMMAND(id, event, func)}}{The same as EVT\_CUSTOM, but +expects a member function with a wxCommandEvent argument.} +\twocolitem{\windowstyle{EVT\_COMMAND\_RANGE(id1, id2, event, func)}}{The same as EVT\_CUSTOM\_RANGE, but +expects a member function with a wxCommandEvent argument.} +\end{twocollist} + +\wxheading{Macros listed by event class} + +The documentation for specific event macros is organised by event class. Please refer +to these sections for details. + +\twocolwidtha{8cm}% +\begin{twocollist}\itemsep=0pt +\twocolitem{\wxhelpref{wxActivateEvent}{wxactivateevent}}{The EVT\_ACTIVATE and EVT\_ACTIVATE\_APP macros intercept +activation and deactivation events.} +\twocolitem{\wxhelpref{wxCommandEvent}{wxcommandevent}}{A range of commonly-used control events.} +\twocolitem{\wxhelpref{wxCloseEvent}{wxcloseevent}}{The EVT\_CLOSE macro handles window closure +called via \wxhelpref{wxWindow::Close}{wxwindowclose}.} +\twocolitem{\wxhelpref{wxDropFilesEvent}{wxdropfilesevent}}{The EVT\_DROP\_FILES macros handles +file drop events.} +\twocolitem{\wxhelpref{wxEraseEvent}{wxeraseevent}}{The EVT\_ERASE\_BACKGROUND macro is used to handle window erase requests.} +\twocolitem{\wxhelpref{wxFocusEvent}{wxfocusevent}}{The EVT\_SET\_FOCUS and EVT\_KILL\_FOCUS macros are used to handle keyboard focus events.} +\twocolitem{\wxhelpref{wxKeyEvent}{wxkeyevent}}{EVT\_CHAR and EVT\_CHAR\_HOOK macros handle keyboard +input for any window.} +\twocolitem{\wxhelpref{wxIdleEvent}{wxidleevent}}{The EVT\_IDLE macro handle application idle events +(to process background tasks, for example).} +\twocolitem{\wxhelpref{wxInitDialogEvent}{wxinitdialogevent}}{The EVT\_INIT\_DIALOG macro is used +to handle dialog initialisation.} +\twocolitem{\wxhelpref{wxListEvent}{wxlistevent}}{These macros handle \wxhelpref{wxListCtrl}{wxlistctrl} events.} +\twocolitem{\wxhelpref{wxMenuEvent}{wxmenuevent}}{These macros handle special menu events (not menu commands).} +\twocolitem{\wxhelpref{wxMouseEvent}{wxmouseevent}}{Mouse event macros can handle either individual +mouse events or all mouse events.} +\twocolitem{\wxhelpref{wxMoveEvent}{wxmoveevent}}{The EVT\_MOVE macro is used to handle a window move.} +\twocolitem{\wxhelpref{wxPaintEvent}{wxpaintevent}}{The EVT\_PAINT macro is used to handle window paint requests.} +\twocolitem{\wxhelpref{wxScrollEvent}{wxscrollevent}}{These macros are used to handle scroll events from +\wxhelpref{wxScrollBar}{wxscrollbar}, \wxhelpref{wxSlider}{wxslider},and \wxhelpref{wxSpinButton}{wxspinbutton}.} +\twocolitem{\wxhelpref{wxSizeEvent}{wxsizeevent}}{The EVT\_SIZE macro is used to handle a window resize.} +\twocolitem{\wxhelpref{wxSplitterEvent}{wxsplitterevent}}{The EVT\_SPLITTER\_SASH\_POS\_CHANGED, EVT\_SPLITTER\_UNSPLIT +and EVT\_SPLITTER\_DOUBLECLICKED macros are used to handle the various splitter window events.} +\twocolitem{\wxhelpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}}{The EVT\_SYS\_COLOUR\_CHANGED macro is used to handle +events informing the application that the user has changed the system colours (Windows only).} +\twocolitem{\wxhelpref{wxTreeEvent}{wxtreeevent}}{These macros handle \wxhelpref{wxTreeCtrl}{wxtreectrl} events.} +\twocolitem{\wxhelpref{wxUpdateUIEvent}{wxupdateuievent}}{The EVT\_UPDATE\_UI macro is used to handle user interface +update pseudo-events, which are generated to give the application the chance to update the visual state of menus, +toolbars and controls.} +\end{twocollist} diff --git a/docs/latex/book/chap_install.tex b/docs/latex/book/chap_install.tex index dd73adc788..88c991a87a 100644 --- a/docs/latex/book/chap_install.tex +++ b/docs/latex/book/chap_install.tex @@ -3,5 +3,462 @@ \setheader{{\it CHAPTER \thechapter: INSTALLING wxWINDOWS}}{}{}{}{}{{\it CHAPTER \thechapter: INSTALLING wxWINDOWS}}% \setfooter{\thepage}{}{}{}{}{\thepage}% -Installing wxWindows (and what tools to use). +CONTENTS: Installing wxWindows (and what tools to use). + +Installing wxWindows isn't too hard. Each platform has a different method, so we'll look +at each major platform in turn. + +\section{Unix: GTK+ and Motif}\label{installunix} + +\subsection{The most simple case} + +If you are compile wxWindows on Linux for the first time and don't like to read +install instructions, just do this in the base directory: + +\begin{verbatim} + ./configure --with-gtk + make + su + make install + ldconfig + exit +\end{verbatim} + +This is using the GTK+ port. If using the Motif port, type --with-motif instead of --with-gtk. + +Afterwards you can continue with: + +\begin{verbatim} + make + su + make install + ldconfig + exit +\end{verbatim} + +If you want to remove wxWindows on Unix you can do this: + +\begin{verbatim} + su + make uninstall + ldconfig + exit +\end{verbatim} + +\subsection{The expert case} + +If you want to do some more serious cross-platform programming with wxWindows, +such as for GTK and Motif, you can now build two complete libraries and use +them concurrently. For this end, you have to create a directory for each build +of wxWindows - you may also want to create different versions of wxWindows +and test them concurrently. Most typically, this would be a version configured +with --enable-debug\_flag and one without. Note, that only one build can currently +be installed, so you'd have to use a local version of the library for that purpose. +For building three versions (one for GTK+, one for Motif and a debug GTK+ version) you'd do this: + +\begin{verbatim} + md buildmotif + cd buildmotif + ../configure --with-motif + make + cd .. + + md buildgtk + cd buildgtk + ../configure --with-gtk + make + cd .. + + md buildgtkd + cd buildgtkd + ../configure --with-gtk --enable-debug_flag + make + cd .. +\end{verbatim} + +\subsection{The most simple errors} + +\begin{itemize}\itemsep=0pt +\item Configure reports, that you don't have GTK 1.2 installed although you are +very sure you have. Well, you have installed it, but you also have another +version of the GTK installed, which you may need to remove including other +versions of glib (and its headers). Also, look for the PATH variable and check +if it includes the path to the correct gtk-config! The check your LDPATH if it +points to the correct library. There is no way to compile wxGTK if configure +doesn't pass this test as all this test does is compile and link a GTK program. +\item You get errors during compilation: The reason is that you probably have a broken +compiler, which includes almost everything that is called gcc. If you use gcc 2.8 +you have to disable optimsation as the compiler will give up with an internal +compiler error.You get immediate segfault when starting any sample or application: This is either +due to having compiled the library with different flags or options than your program - +typically you might have the __WXDEBUG__ option set for the library but not for your +program - or due to using a broken compiler (and its optimisation) such as GCC 2.8. +\end{itemize} + +\subsection{The most simple program} + +Now create your super-application myfoo.app and compile anywhere with: + +\begin{verbatim} + gcc myfoo.cpp `wx-config --libs --cflags` -o myfoo +\end{verbatim} + +\wxheading{General} + +The Unix variants of wxWindows use GNU configure. If you have problems with your +make use GNU make instead. + +If you have general problems with installation, visit Robert Roebling's homepage at + +\begin{verbatim} + http://wesley.informatik.uni-freiburg.de/~wxxt +\end{verbatim} + +for the latest information. If you still don't have any success, please send a bug +report to one of the mailing lists. + +\wxheading{Libraries needed} + +wxWindows/GTK requires the GTK+ library to be installed on your system. It has to +be a stable version, preferebly version 1.2.3. + +You can get the newest version of the GTK+ from the GTK homepage at: + +\begin{verbatim} + http://www.gtk.org +\end{verbatim} + +wxWindows/Gtk requires a thread library and X libraries known to work with threads. +This is the case on all commercial Unix-Variants and all Linux-Versions that are +based on glibc 2 except RedHat 5.0 which is broken in many aspects. As of writing +this, these Linux distributions have correct glibc 2 support: + +\begin{itemize}\itemsep=0pt +\item RedHat 5.1 +\item Debian 2.0 +\item Stampede +\item DLD 6.0 +\item SuSE 6.0 +\end{itemize} + +You can disable thread support by running + +\begin{verbatim} +./configure "--disable-threads" +make +su +make install +ldconfig +exit +\end{verbatim} + +\subsection{Building wxGTK on OS/2} + +Please send comments and question about the OS/2 installation +to Andrea Venturoli and patches to +the wxWindows mailing list. + +You'll need OS/2 Warp (4.00FP#6), X-Free86/2 (3.3.3 or newer), +GTK+ (1.2.5 or newer), emx (0.9d fix 1), flex (2.5.4), yacc (1.8), +korn shell (5.2.13), Autoconf (2.13), GNU file utilities (3.6), +GNU text utilities (1.3), GNU shell utilites (1.12), m4 (1.4), +sed (2.05), grep (2.0), Awk (3.0.3), GNU Make (3.76.1). + +Open an OS/2 prompt and switch to the directory above. +First set some global environment variables we need: + +\begin{verbatim} + SET CXXFLAGS=-Zmtd -D__ST_MT_ERRNO__ + SET CFLAGS=-Zmtd -D__ST_MT_ERRNO__ + SET OSTYPE=OS2X + SET COMSPEC=sh + \end{verbatim} + +Notice you can choose whatever you want, if you don't like OS2X. + +Now, run autoconf in the main directory and in the samples, demos +and utils subdirectory. This will generate the OS/2 specific +versions of the configure scripts. Now run + +\begin{verbatim} + configure --with-gtk +\end{verbatim} + +as described above. + +If you have pthreads library installed, but have a gtk version +which does not yet support threading, you need to explicitly +diable threading by using the option --disable-threads. + +Note that configure assumes your flex will generate files named +"lexyy.c", not "lex.yy.c". If you have a version which does +generate "lex.yy.c", you need to manually change the generated +makefile. + +\subsection{Building wxGTK on SGI} + +Using the SGI native compilers, it is recommended that you +also set CFLAGS and CXXFLAGS before running configure. These +should be set to: + +\begin{verbatim} + CFLAGS="-mips3 -n32" + CXXFLAGS="-mips3 -n32" +\end{verbatim} + +This is essential if you want to use the resultant binaries +on any other machine than the one it was compiled on. If you +have a 64-bit machine (Octane) you should also do this to ensure +you don't accidently build the libraries as 64bit (which is +untested). + +The SGI native compiler support has only been tested on Irix 6.5. + +\subsection{Create your configuration} + +Usage: + +\begin{verbatim} + ./configure options +\end{verbatim} + +If you want to use system's C and C++ compiler, +set environment variables CC and CCC as + +\begin{verbatim} + setenv CC cc + setenv CCC CC + ./configure options +\end{verbatim} + +to see all the options please use: + +\begin{verbatim} + ./configure --help +\end{verbatim} + +The basic philosophy is that if you want to use different +configurations, like a debug and a release version, +or use the same source tree on different systems, +you have only to change the environment variable OSTYPE. +(Sadly this variable is not set by default on some systems +in some shells - on SGI's for example). So you will have to +set it there. This variable HAS to be set before starting +configure, so that it knows which system it tries to +configure for. + +Configure (and sometimes make) will complain if the system variable OSTYPE has +not been defined. + +\subsubsection{General options} + +Given below are the commands to change the default behaviour, +i.e. if it says "--disable-threads" it means that threads +are enabled by default. + +Normally, you won't have to choose a toolkit, because when +you download wxGTK, it will default to --with-gtk etc. But +if you use all of our CVS repository you have to choose a +toolkit. You must do this by running configure with either of: + +\begin{verbatim} + --without-gtk Don't use the GIMP ToolKit (GTK) + + --with-motif Use either Motif or Lesstif + Configure will look for both. +\end{verbatim} + +The following options handle the kind of library you want to build. + +\begin{verbatim} + --disable-threads Compile without thread support. + + --disable-shared Do not create shared libraries. + + --enable-static Create static libraries. + + --disable-optimise Do not optimise the code. Can + sometimes be useful for debugging + and is required on some architectures + such as Sun with gcc 2.8.X which + and otherwise produce segvs. + + --enable-profile Add profiling info to the object + files. Currently broken, I think. + + --enable-no_rtti Enable compilation without creation of + C++ RTTI information in object files. + This will speed-up compilation and reduce + binary size. + + --enable-no_exceptions Enable compilation without creation of + C++ exception information in object files. + This will speed-up compilation and reduce + binary size. Also fewer crashes during the + actual compilation... + + --enable-no_deps Enable compilation without creation of + dependency information. + + --enable-permissive Enable compilation without creation of + giving erros as soon as you compile with + Solaris' ANSI-defying headers. + + --enable-mem_tracing Add built-in memory tracing. + + --enable-dmalloc Use the dmalloc memory debugger. + Read more at www.letters.com/dmalloc/ + + --enable-debug_info Add debug info to object files and + executables for use with debuggers + such as gdb (or its many frontends). + + --enable-debug_flag Define __DEBUG__ and __WXDEBUG__ when + compiling. This enable wxWindows' very + useful internal debugging tricks (such + as automatically reporting illegal calls) + to work. Note that program and library + must be compiled with the same debug + options. +\end{verbatim} + +\subsubsection{Feature Options} + +When producing an executable that is linked statically with wxGTK +you'll be surprised at its immense size. This can sometimes be +drastically reduced by removing features from wxWindows that +are not used in your program. The most relevant such features +are + +\begin{verbatim} + --with-odbc Enables ODBC code. This is disabled + by default because iODBC is under the + L-GPL license. + + --without-libpng Disables PNG image format code. + + --without-libjpeg Disables JPEG image format code. + + --without-libtiff Disables TIFF image format code. + + --disable-pnm Disables PNM image format code. + + --disable-gif Disables GIF image format code. + + --disable-pcx Disables PCX image format code. + + --disable-resources Disables the use of *.wxr type + resources. + + --disable-threads Disables threads. Will also + disable sockets. + + --disable-sockets Disables sockets. + + --disable-dnd Disables Drag'n'Drop. + + --disable-clipboard Disables Clipboard. + + --disable-serial Disables object instance serialiasation. + + --disable-streams Disables the wxStream classes. + + --disable-file Disables the wxFile class. + + --disable-textfile Disables the wxTextFile class. + + --disable-intl Disables the internationalisation. + + --disable-validators Disables validators. + + --disable-accel Disables accel. +\end{verbatim} + +Apart from disabling certain features you can very often "strip" +the program of its debugging information resulting in a significant +reduction in size. + +\subsubsection{Compiling} + +The following must be done in the base directory (e.g. ~/wxGTK +or ~/wxWin or whatever) + +Now the makefiles are created (by configure) and you can compile +the library by typing: + +\begin{verbatim} + make +\end{verbatim} + +make yourself some coffee, as it will take some time. On an old +386SX possibly two weeks. During compilation, you'll get a few +warning messages depending in your compiler. + +If you want to be more selective, you can change into a specific +directiry and type "make" there. + +Then you may install the library and it's header files under +/usr/local/include/wx and /usr/local/lib respectively. You +have to log in as root (i.e. run "su" and enter the root +password) and type + +\begin{verbatim} + make install +\end{verbatim} + +You can remove any traces of wxWindows by typing + +\begin{verbatim} + make uninstall +\end{verbatim} + +If you want to save disk space by removing unnecessary +object-files: + +\begin{verbatim} + make clean +\end{verbatim} + +in the various directories will do the work for you. + +\subsubsection{Creating a new Project} + +1) The first way uses the installed libraries and header files +automatically using wx-config + +\begin{verbatim} +gcc myfoo.cpp `wx-config --cflags --libs` -o myfoo +\end{verbatim} + +Using this way, a make file for the minimal sample would look +like this + +\begin{verbatim} +CC = gcc + +minimal: minimal.o + $(CC) -o minimal minimal.o `wx-config --libs` + +minimal.o: minimal.cpp mondrian.xpm + $(CC) `wx-config --cflags` -c minimal.cpp -o minimal.o + +clean: + rm -f *.o minimal +\end{verbatim} + +This is certain to become the standard way unless we decide +to sitch to tmake. + +2) The other way creates a project within the source code +directories of wxWindows. For this endeavour, you'll need +GNU autoconf version 2.14 and add an entry to your Makefile.in +to the bottom of the configure.in script and run autoconf +and configure before you can type make. + +\section{Windows}\label{installwindows} + + +\section{Mac}\label{installmac} + +We don't have information about Mac installation at this time. diff --git a/docs/latex/book/chap_intro.tex b/docs/latex/book/chap_intro.tex index 8fcc818908..132a143725 100644 --- a/docs/latex/book/chap_intro.tex +++ b/docs/latex/book/chap_intro.tex @@ -19,7 +19,7 @@ desktop, where the high price of Windows gives it an advantage. Apple has made an impressive comeback and is revamping its own operating system. The embedded market continues to explode and has given rise to new niches for specialist operating systems. -The keyword bow is diversity, when the best guess of a few years +The keyword now is diversity, when the best guess of a few years was that Microsoft would conquer all. More than ever, application developers need to keep their options open and targeting one platform only can be a recipe for commercial (or diff --git a/docs/latex/book/makefile.vc b/docs/latex/book/makefile.vc index c53748c104..74ae66d6c8 100644 --- a/docs/latex/book/makefile.vc +++ b/docs/latex/book/makefile.vc @@ -10,7 +10,7 @@ THISDIR=$(WXWIN)\src\msw # WXDIR=$(WXWIN) -WXDIR=d:\wx2\wxWindows +WXDIR=$(WXWIN) DOCDIR = $(WXDIR)\docs diff --git a/docs/latex/book/tex2rtf.ini b/docs/latex/book/tex2rtf.ini index d35f4f1bbc..692855df67 100644 --- a/docs/latex/book/tex2rtf.ini +++ b/docs/latex/book/tex2rtf.ini @@ -1,4 +1,4 @@ -; Last change: JAC 18 Aug 100 12:58 pm +; Last change: JAC 23 Nov 100 8:27 pm ;;; Tex2RTF initialisation file runTwice = yes titleFontSize = 12 @@ -37,4 +37,8 @@ htmlIndex = true \pythonnote [1] {{\bf \fcol{blue}{wxPython note:}} #1} %\pythonnote [1] {} +% Use this if not including the class reference in the book +\wxhelpref [2] {#1} +% Use this if including the class reference in the book +%\wxhelpref [2] {\helpref{#1}{#2}} -- 2.47.2