diff --git a/docs/contributing/about-platform-toolkit-and-library-names.txt b/docs/contributing/about-platform-toolkit-and-library-names.txt new file mode 100644 index 0000000000..3115bbace1 --- /dev/null +++ b/docs/contributing/about-platform-toolkit-and-library-names.txt @@ -0,0 +1,122 @@ + wxWidgets naming conventions + ============================ + +Being a cross platform development library, it is naturally desirable +(at least to me ;) for wxWidgets to be exploited in a fully cross +platform development environment -- a single invocation of make should +be sufficient to build target executables for a variety of host platforms +when desired. + +Since this is now in fact possible for at least the most commonly used +platforms, wxWidgets has been structured to allow multiple, simultaneous +installations of the library. Common files are shared, platform and port +specific files and libraries are arranged so as to be unambiguous when +installed together. + +To manage this sanely we need a sufficiently descriptive and logical +labelling convention for file and install path names -- this document (at +least at its time of writing) describes the system we have adopted. + +It is not fine grained enough to include every possible build configuration +for wxWidgets, but is encompassing enough to maintain a relatively complete +set of cross platform build tools on a single machine and to provide an +obvious slot for new ports to slip into. + + +For UNIX libraries, the canonical library name shall be of the form: + +libwx_$(toolkit)$(widgetset)$(debug)-$(version)-$(host).$(lib_extension) + +For MSW (native hosted only) libraries the library name should be of +the form: + +wx$(toolkit)$(widgetset)$(version)$(unicode)$(debug).$(lib_extension) + + +Where: + +-------------------------------------------------------------------- + +$toolkit must currently be one of the following: + + msw + gtk + base + mac + motif + +-------------------------------------------------------------------- + +$widgetset may be one of: + + univ + +or empty if the widget set is the same as the toolkit. + +-------------------------------------------------------------------- + +$version is a string encoding the full version (major, minor, release) +for MSW, or just the major and minor number for UNIX. + +eg. for wxWidgets 2.3.2, $version = 232 for MSW or 2.3 for UNIX. + +The rationale for this is that under UNIX-like systems it is desirable +that differently 'minor numbered' releases can be installed together, +meaning your old 2.2 apps can continue to work even if you migrate +development to the next stable or unstable release (eg. 2.3, 2.4), +but binary compatibility is maintained between point releases (those +with the same major.minor number) + +A known break in binary compatibility should be addressed by updating +the library soname (see the notes in configure.in for details on this) + +I do not know why MSW should not also omit the release number from +$version. (maybe that will change by the time this document is ratified) + +-------------------------------------------------------------------- + +$unicode and $debug are either empty or set to 'u' and 'd' +respectively when enabled. + +-------------------------------------------------------------------- + +$host is empty for a 'native' library, (that is one where the host +system is the same as the build system) or set to the value returned +by the autoconf ${host_alias} variable in configure for libraries +that are cross compiled. + +-------------------------------------------------------------------- + +$lib_extension is system specific and most usually set to .a for +a static library, .dll for a MSW shared library, or .so.$so_version +for a shared UNIX library. + +==================================================================== + + +The installed location of the library specific setup.h is also +determined by the values of these items. On UNIX systems they +will be found in: + +$(prefix)/lib/wx/include/$(toolkit)$(widgetset)$(debug)-$(version)-$(host)/wx/ + +which will be in the include search path returned by the relevant +wx-config for that library. (or presumably set in the relevant +make/project files for platforms that do not use wx-config) + +==================================================================== + + +The port specific wx-config file for each library shall be named: + +wx-$(toolkit)$(widgetset)$(debug)-$(version)-$(host)-config + +${prefix}/bin/wx-config shall exist as a link to (or copy of) one of +these port specific files (on platforms which support it) and as such +it defines the default build configuration for wxApps on the system. +It may be modified by the system user at any time. + + + + ---==O==--- + diff --git a/docs/contributing/about-version-numbers.txt b/docs/contributing/about-version-numbers.txt new file mode 100644 index 0000000000..4dd490dec8 --- /dev/null +++ b/docs/contributing/about-version-numbers.txt @@ -0,0 +1,51 @@ + All about wxWidgets Version Numbers + =================================== + +1. Where to update the version numbers: + + There are several places in the wxWidgets source tree that + define the version number for the library. + + The script misc/scripts/inc_release can be used for incrementing the release + field of the version, i.e. changing 2.8.x to 2.8.x+1 but it does not take + care of version.bkl and can't be used for changing the other version + components, this needs to be done manually. It also doesn't update + version.bkl file which always needs to be updated manually, follow the + instructions there. + + Here is the list of files that need to be updated: + + build/bakefiles/version.bkl {C:R:A} [NOT UPDATED AUTOMATICALLY] + build/bakefiles/wxpresets/presets/wx.bkl [NOT UPDATED AUTOMATICALLY] + configure.in + build/osx/wxvers.xcconfig + docs/changes.txt + docs/readme.txt (date needs manual editing) [NOT UPDATED AUTOMATICALLY] + docs/doxygen/Doxyfile (PROJECT_NUMBER and DOCSET_FEEDNAME) + docs/doxygen/latexdocstart.inc + docs/doxygen/mainpages/manual.h (just date) [NOT UPDATED AUTOMATICALLY] + docs/msw/install.txt {major release only} + include/wx/version.h + include/wx/osx/config_xcode.h + samples/Info.plist + samples/docview/Info.plist + samples/minimal/Info_carbon.plist + samples/minimal/Info_cocoa.plist + samples/minimal/borland_ide.cpp {major release only} + + Do not forget to rebake everything after updating version.bkl! + +2. When to update the version numbers: + + Version should be updated immediately after releasing the previous version + so that the sources in the repository always correspond to the next release + and not the past one. + + See also tn0020.txt. + + + + +=== EOF === + + diff --git a/docs/contributing/binary-compatibility.txt b/docs/contributing/binary-compatibility.txt new file mode 100644 index 0000000000..69f610d2e7 --- /dev/null +++ b/docs/contributing/binary-compatibility.txt @@ -0,0 +1,287 @@ + Binary Compatibility and wxWidgets + ================================== +0. Purpose +---------- + +This is a broad technote covering all aspects of binary compatibility with +wxWidgets. + +1. Releases +----------- + +General overview of releases can be found in tn0012.txt, but for +completeness the wxWidgets release version number is as follows: + +2.6.2 + +Where + + 2 6 2 +Major Minor Release + +(I.E. Major.Minor.Release). + +All versions with EVEN minor version component (e.g. 2.4.x, 2.6.x etc.) +are expected to be binary compatible (ODD minors are development versions +and the compatibility constraints don't apply to them). Note that by +preserving binary compatibility we mean BACKWARDS compatibility only, +meaning that applications built with old wxWidgets headers should continue +to work with new wxWidgets (shared/dynamic) libraries without the need to +rebuild. There is no requirement to preserve compatibility in the other +direction (i.e. make new headers compatible with old libraries) as this +would preclude any additions whatsoever to the stable branch. But see +also section (4). + + +2. What kind of changes are NOT binary compatible +------------------------------------------------- + +If its still up, the KDE guide is a good reference: +http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C++ + +The changes that are NOT binary compatible: +- Adding a virtual function +- Changing the name of a any function or variable +- Changing the signature of a virtual function (adding a parameter, +even a default one) +- Changing the order of the virtual functions in a class +["switching" them, etc.] +- Changing access privileges of a function: some compilers (among which MSVC) + use the function access specifier in its mangled name. Moreover, while + changing a private function to public should be compatible (as the old + symbol can't be referenced from outside the library anyhow), changing a + virtual private function to public is NOT compatible because the old symbol + is referenced by the virtual tables in the executable code and so an old + program compiled with MSVC wouldn't start up with a new DLL even if it + doesn't use the affected symbol at all! +- Adding a member variable +- Changing the order of non-static member variables + + +3. Changes which are compatible +------------------------------- + +- Adding a new class +- Adding a new non-virtual method to an existing class +- Adding a new constructor to an existing class +- Overriding the implementation of an existing virtual function +[this is considered to be backwards binary compatible until we find a + counter example; currently it's known to work with Apple gcc at least] +- Anything which doesn't result in ABI change at all, e.g. adding new + macros, constants and, of course, private changes in the implementation + + +4. wxABI_VERSION and "forward" binary compatibility +-------------------------------------------------- + +As mentioned we do not support "forward" binary compatibility, that is the +ability to run applications compiled with new wxWidgets headers on systems +with old wxWidgets libraries. + +However, for the developers who want to ensure that their application works +with some fixed old wxWidgets version and doesn't (inadvertently) require +features added in later releases, we provide the macro wxABI_VERSION which +can be defined to restrict the API exported by wxWidgets headers to that of +a fixed old release. + +For this to work, all new symbols added to binary compatible releases must +be #if'ed with wxABI_VERSION. + +The layout of wxABI_VERSION is as follows: + +20602 + +where + + 2 06 02 +Major Minor Release + +I.E. it corresponds to the wxWidgets release in (1). + +An example of using wxABI_VERSION is as follows for symbols +only in a 2.6.2 release: + +#if wxABI_VERSION >= 20602 /* 2.6.2+ only */ +bool Load(const wxURI& location, const wxURI& proxy); + +wxFileOffset GetDownloadProgress(); +wxFileOffset GetDownloadTotal(); + +bool ShowPlayerControls( + wxMediaCtrlPlayerControls flags = + wxMEDIACTRLPLAYERCONTROLS_DEFAULT); + +//helpers for the wxPython people +bool LoadURI(const wxString& fileName) +{ return Load(wxURI(fileName)); } +bool LoadURIWithProxy(const wxString& fileName, const wxString& proxy) +{ return Load(wxURI(fileName), wxURI(proxy)); } +#endif + + +5. Workarounds for adding virtual functions +------------------------------------------- + +Originally the idea for adding virtual functions to binary compatible +releases was to pad out some empty "reserved" functions and then +rename those later when someone needed to add a virtual function. + +However, after there was some actual testing of the idea a lot of +controversy erupted. Eventually we decided against the idea, and +instead devised a new method for doing so called wxShadowObject. + +wxShadowObject is a class derived from wxObject that provides a means +of adding functions and/or member variables to a class internally +to wxWidgets. It does so by storing these in a hash map inside of +it, looking it up when the function etc. is called. wxShadowObject +is generally stored inside a reserved member variable. + +wxShadowObject resides in include/wx/clntdata.h. + +To use wxShadowObject, you first call AddMethod or AddField with +the first parameter being the name of the field and/or method +you want, and the second parameter being the value of the +field and/or method. + +In the case of fields this is a void*, and in the case of method +is a wxShadowObjectMethod which is a typedef: +typedef int (*wxShadowObjectMethod)(void*, void*); + +After you add a field, you can set it via SetField with the same +parameters as AddField, the second parameter being the value to set +the field to. You can get the field after you call AddField +via GetField, with the parameters as the other two field functions, +only in the case the second parameter is the fallback +value for the field in the case of it not being found in the +hash map. + +You can call a method after you add it via InvokeMethod, which +returns a bool indicating whether or not the method was found +in the hash map, and has 4 parameters. The first parameter is +the name of the method you wish to call, the second is the first +parameter passed to the wxShadowObjectMethod, the third is the +second parameter passed to that wxShadowObjectMethod, and the +fourth is the return value of the wxShadowObjectMethod. + +6. version-script.in +-------------------- + +For ld/libtool we use sun-style version scripts. Basically +anything which fits the conditions of being #if'ed via wxABI_VERSION +needs to go here also. + +See 'info ld scripts version' on a GNU system, it's online here: +http://www.gnu.org/software/binutils/manual/ld-2.9.1/html_node/ld_25.html + +Or see chapter 5 of the 'Linker and Libraries Guide' for Solaris, available +online here: +http://docsun.cites.uiuc.edu/sun_docs/C/solaris_9/SUNWdev/LLM/p1.html + +The file has the layout as follows: + +@WX_VERSION_TAG@.X + +Where X is the current Release as mentioned earlier, i.e. 2. This +is following by an opening bracket "{", followed by "global:", +followed by patterns matching added symbols, then followed by "}", and then +the file is either followed by earlier Releases or ended by +a @WX_VERSION_TAG@ block without the period or Release. + +The patterns used to specify added symbols are globbing patters and can +contain wildcards such as '*'. + +For example for a new class member such as: + wxFont wxGenericListCtrl::GetItemFont( long item ) const; + +the mangled symbol might be: + _ZNK17wxGenericListCtrl11GetItemFontEl + +so a line like this could be added to version-script.in: + *wxGenericListCtrl*GetItemFont*; + +Allow for the fact that the name mangling is going to vary from compiler to +complier. + +When adding a class you can match all the symbols it adds with a single +pattern, so long as that pattern is not likely to also match other symbols. +For example for wxLogBuffer a line like this: + *wxLogBuffer*; + + +7. Checking the version information in libraries and programs +------------------------------------------------------------- + +On Sun there is a tool for this, see pvs(1). On GNU you can use objdump, below +are some examples. + +To see what versions of each library a program (or library) depends on: + +$ objdump -p widgets | sed -ne '/Version References/,/^$/p' +Version References: + required from libgcc_s.so.1: + 0x0b792650 0x00 10 GCC_3.0 + required from libwx_based-2.6.so.0: + 0x0cca2546 0x00 07 WXD_2.6 + required from libstdc++.so.6: + 0x056bafd3 0x00 09 CXXABI_1.3 + 0x08922974 0x00 06 GLIBCXX_3.4 + required from libwx_gtk2d_core-2.6.so.0: + 0x0a2545d2 0x00 08 WXD_2.6.2 + 0x0cca2546 0x00 05 WXD_2.6 + required from libc.so.6: + 0x09691a75 0x00 04 GLIBC_2.2.5 + +To see what WXD_2.6.2 symbols a program uses: + +$ objdump -T widgets | grep 'WXD_2\.6\.2' +0000000000000000 g DO *ABS* 0000000000000000 WXD_2.6.2 WXD_2.6.2 +00000000004126d8 DF *UND* 0000000000000177 WXD_2.6.2 _ZN19wxTopLevelWindowGTK20RequestUserAttentionEi + +To see what WXD_2.6.2 symbols a library defines: + +$ objdump -T libwx_based-2.6.so | grep 'WXD_2\.6\.2' | grep -v 'UND\|ABS' +0000000000259a10 w DO .data 0000000000000018 WXD_2.6.2 _ZTI19wxMessageOutputBest +00000000002599e0 w DO .data 0000000000000028 WXD_2.6.2 _ZTV19wxMessageOutputBest +000000000010a98e w DF .text 000000000000003e WXD_2.6.2 _ZN19wxMessageOutputBestD0Ev +0000000000114efb w DO .rodata 000000000000000e WXD_2.6.2 _ZTS11wxLogBuffer +0000000000255590 w DO .data 0000000000000018 WXD_2.6.2 _ZTI11wxLogBuffer +000000000011b550 w DO .rodata 0000000000000016 WXD_2.6.2 _ZTS19wxMessageOutputBest +00000000000bfcc8 g DF .text 00000000000000dd WXD_2.6.2 _ZN11wxLogBuffer5DoLogEmPKcl +000000000010a3a6 g DF .text 0000000000000153 WXD_2.6.2 _ZN19wxMessageOutputBest6PrintfEPKcz +00000000000c0b22 w DF .text 000000000000004b WXD_2.6.2 _ZN11wxLogBufferD0Ev +00000000000bfc3e g DF .text 0000000000000089 WXD_2.6.2 _ZN11wxLogBuffer5FlushEv +00000000000c0ad6 w DF .text 000000000000004b WXD_2.6.2 _ZN11wxLogBufferD1Ev +00000000000b1130 w DF .text 0000000000000036 WXD_2.6.2 _ZN11wxLogBufferC1Ev +00000000000c095c w DF .text 0000000000000029 WXD_2.6.2 _ZN19wxMessageOutputBestC1Ev +00000000000c08e8 w DF .text 000000000000003e WXD_2.6.2 _ZN19wxMessageOutputBestD1Ev +00000000002554c0 w DO .data 0000000000000038 WXD_2.6.2 _ZTV11wxLogBuffer +00000000000bfda6 g DF .text 0000000000000036 WXD_2.6.2 _ZN11wxLogBuffer11DoLogStringEPKcl +00000000000abe10 g DF .text 0000000000000088 WXD_2.6.2 _ZN14wxZipFSHandler7CleanupEv + + +8. Testing binary compatibility between releases +------------------------------------------------ + +An easy way of testing binary compatibility is just to build wxWidgets +in dll/dynamic library mode and then switch out the current library +in question with an earlier stable version of the library, then running +the application in question again. If it runs OK then there is usually +binary compatibility between those releases. + +You can also break into your debugger or whatever program you want +to use and check the memory layout of the class. If it is the same +then it is binary compatible. +(In GDB the command x/d will show addresses as pointers to functions if +possible so you can see if the order of the functions in vtbl doesn't change.) + +Another way to check for binary compatibility is to build wxWidgets in shared mode +and use the 'abicheck.sh --generate' script before doing your changes to generate +the current ABI (if the 'expected_abi' file is not already in the repo). +Then rebuild wxWidgets with your changes and use 'abicheck.sh' to compare the +resulting ABI with the expected one. +Note that the abicheck.sh script is in the "lib" folder. + + +=== EOF === + +Author: RN diff --git a/docs/contributing/how-to-add-class-documentation.txt b/docs/contributing/how-to-add-class-documentation.txt new file mode 100644 index 0000000000..c1050e862c --- /dev/null +++ b/docs/contributing/how-to-add-class-documentation.txt @@ -0,0 +1,315 @@ + Adding wxWidgets class documentation + ==================================== + +This note is aimed at people wishing to add documentation for a +class to either the main wxWidgets manual, or to their own +manual. + +wxWidgets uses Doxygen to process header input files with embedded +documentation in the form of C++ comments and output in HTML, and XML +(Doxygen itself can also output Latex, manpages, RTF, PDF etc). +See http://www.doxygen.org for more info about Doxygen. + +If you want to add documentation of a new class/function to the +existing manual in docs/doxygen, you need to create a new .h file, +e.g. myclass.h, under the interface folder, which contains the public +interface of the new class/function in C++ syntax. +The documentation can then be added in form of Doxygen comments to +the header file. + +You may also want to write a separate topic file, +e.g. docs/doxygen/overviews/myclass.h, and add the entry to +docs/doxygen/mainpages/topics.h. + +If applicable, also add an entry to one of the docs/doxygen/mainpages/cat_*.h +files. + +You can generate a first raw version of myclass.h simply taking its +"real" header and removing all the private and protected sections and +in general removing everything the user "shouldn't know": i.e. all things +which are implementation details. + + +Running Doxygen +=============== + +First, make sure you have a recent version of Doxygen installed in your system +(you'll need Doxygen >= 1.5.7). + +On Unix: + + 1) run wxWidgets/docs/doxygen/regen.sh [format-to-generate] + +On Windows: + 1) cd wxWidgets/docs/doxygen + 2) run regen.bat [format-to-generate] + +If you don't specify which format to [re]generate, all output formats will +be enabled. Possible values for [format-to-generate] are: "html", "chm", "latex", +"xml" and "all". + +The output of Doxygen is all placed in the wxWidgets/docs/doxygen/out folder. + + +Important Dos and Don'ts +======================== + +DO: + +- Doxygen supports both commands in the form \command and @command; + all wxWidgets documentation uses the @command form. + Follow strictly this rule. + +- strive to use dedicated Doxygen commands for e.g. notes, lists, + sections, etc. The "Special commands" page: + http://www.stack.nl/~dimitri/doxygen/commands.html + is your friend! + It's also very important to make a consistent use of the ALIASES + defined by wxWidgets' Doxyfile. Open that file for more info. + +- when you write true, false and NULL with their C++ semantic meaning, + then use the @true, @false and @NULL commands. + +- separate different paragraphs with an empty comment line. + This is important otherwise Doxygen puts everything in the same + paragraph making the result less readable. + +- leave a blank comment line between a @section, @subsection, @page + and the next paragraph. + +- test your changes, both reading the generated HTML docs and by looking + at the "doxygen.log" file produced (which will warn you about any + eventual mistake found in the comments). + +- quote all the following characters prefixing them with a "@" char: + + @ $ \ & < > # % + + unless they appear inside a @code or @verbatim section + (you can also use HTML-style escaping, e.g. & rather than @ escaping) + +- when using a Doxygen alias like @itemdef{}, you need to escape the + comma characters which appear on the first argument, otherwise Doxygen + will interpret them as the marker of the end of the first argument and + the beginning of the second argument's text. + + E.g. if you want to define the item "wxEVT_MACRO(id, func)" you need to + write: + @itemdef{wxEVT_MACRO(id\, func), This is the description of the macro} + + Also note that you need to escape only the commas of the first argument's + text; second argument can have up to 10 commas unescaped (see the Doxyfile + for the trick used to implement this). + +- for linking use one of: + => the @ref command to refer to topic overviews; + => the () suffix to refer to function members of the same class you're + documenting or to refer to global functions or macros; + => the classname:: operator to refer to functions of classes different + from the one you're documenting; + => the :: prefix to refer to global variables (e.g. ::wxEmptyString). + Class names are auto-linked by Doxygen without the need of any explicit + command. + +DON'T: + +- use jargon, such as 'gonna', or omit the definite article. + The manual is intended to be a fluent, English document and + not a collection of rough notes. + +- use non-alphanumeric characters in link anchors. + +- use Doxygen @b @c @e commands when referring to more than a single word; + in that case you need to use the ..., ..., ... + HTML-style tags instead + +- use HTML style tags for creation of tables or lists. + Use wx aliases instead like @beginTable, @row2col, @row3col, @endTable and + @beginDefList, @itemdef, @endDefList, etc. + See the Doxyfile.inc for more info. + + +Documentation comment for a class +================================= + +Start off with: + +/** + @class wxMyClass + + ...here goes the description... + + @beginEventTable + @event{EVT_SOME_EVENT(id, func)}: + Description for EVT_SOME_EVENT. + @endEventTable + + @beginStyleTable + @style{wxSOME_STYLE}: + Description for wxSOME_STYLE. + ... + @endStyleTable + + @beginExtraStyleTable + @style{wxSOME_EXTRA_STYLE}: + Description for wxSOME_EXTRA_STYLE. + ... + @endExtraStyleTable + + @library{wxbase} + @category{cat_shortcut} + + @nativeimpl{wxgtk, wxmsw, ...} + @onlyfor{wxgtk, wxmsw, ...} + + @appearance{button.png} + + @stdobjects + ...here goes the list of predefined instances... + + @see ...here goes the see-also list... + you can make references to topic overviews or other + manual pages using the @ref command +*/ + +Note that everything *except* the @class, @library and @category +commands are optionals. + +Also note that if you use @section and @subsection in the class description +(at the beginning), you should use as the section's anchor name "xxxx_yyyy" +where "xxxx" is the class name without the initial "wx" in lowercase +and "yyyy" is a lowercase word which uniquely identifies that section. +E.g.: + +/** + @class wxMyClass + + This class does not exist really and is only used as an example + of best documentation practices. + + @section myclass_special Special functions of this class + + This section describes the functions whose usage is reserved for + wxWidgets internal mechanisms... etc etc... + + + @section myclass_custom Customizing wxMyClass + + What if you want to customize this powerful class? + First you should do this and that, etc etc... + + + @library{wxbase} + @category{misc} + + @see wxMyOtherClass +*/ + + + +Documentation comment for a function +==================================== + +Start off with: + +/** + ...here goes the description of the function.... + + @param param1 + ...here goes the description for the first parameter of this function + @param param2 + ...here goes the description for the second parameter of this function + ... + + @return + ...here goes the description of what the function returns... + + @note ...here go any eventual notes about this function... + + @remarks ...here go any eventual remarks about this function... + + @see ...here goes the see-also list... + */ + +Note that the @return, @note, @remarks, @see commands are optional. + +The @param command has an optional attribute specifying the direction of +the attribute. Possible values are "in" and "out". E.g. + +/** + * Copies bytes from a source memory area to a destination memory area, + * where both areas may not overlap. + * @param[out] dest The memory area to copy to. + * @param[in] src The memory area to copy from. + * @param[in] n The number of bytes to copy. + * @param[in,out] pmisc Used both as input and as output. + */ +void func(void *dest, const void *src, size_t n, void *pmisc); + + +Documentation comment for a topic overview +========================================== + +Topic overviews are stored inside the docs/doxygen/overviews folder +and are completely placed inside a single comment block in the form of: + +/*! + + @page overview_tname wxSomeStuff overview + + This page provides an overview of the wxSomeStuff and related classes. + .... + + @li @ref overview_tname_intro + @li @ref overview_tname_details + ... + +
+ + + @section overview_tname_intro Introduction + + ...here goes the introduction to this topic... + + + @section overview_tname_details Details + + ...here go the details to this topic... + +*/ + +Note that there is a convention in the anchor link names. +Doxygen in fact requires that for each @page, @section, @subsection, etc tag, +there is a corresponding link anchor. + +The following conventions are used in wxWidgets doxygen comments: + +1) all "main" pages of the manual (those which are placed in + docs/doxygen/mainpages) have link anchors which begin with "page_" + +2) all topic overviews (those which are placed in docs/doxygen/overviews) have + link anchors which begin with "overview_" + +3) all @section, @subsection, @subsubsection tags should have as link anchor + name the name of the parent section plus a specific word separated with an + underscore; e.g.: + +/*! + + @page overview_tname wxSomeStuff overview + + @section overview_tname_intro Introduction + @subsection overview_tname_intro_firstpart First part + @subsection overview_tname_intro_secondpart Second part + @subsubsection overview_tname_intro_secondpart_sub Second part subsection + @subsection overview_tname_intro_thirdpart Third part + + @section overview_tname_details Details + ... + +*/ + + +=== EOF === + +Author: FM (along the lines of the previous technote about tex2rtf) diff --git a/docs/contributing/how-to-add-files-to-build-system.txt b/docs/contributing/how-to-add-files-to-build-system.txt new file mode 100644 index 0000000000..6b142b0603 --- /dev/null +++ b/docs/contributing/how-to-add-files-to-build-system.txt @@ -0,0 +1,227 @@ + How to add new files and libraries to wxWidgets build system + ============================================================ + + +1. Regenerating makefiles +------------------------- + +wxWidgets now uses Bakefile (http://bakefile.sourceforge.net) to generate +native makefiles. You must have bakefile installed if you want to regenerate +the makefiles. Bakefile currently runs on Unix and Windows systems. You will +need Python >= 2.2 installed on Unix and either use Bakefile installer or have +Python on Windows. + +Once you have installed Bakefile, you can easily regenerate the makefiles using +the bakefile_gen tool. Run it from $(wx)/build/bakefiles directory and it will +regenerate all outdated makefiles. See $(wx)/build/bakefiles/README for more +details. + +Note that it generates makefiles for samples, too. + +IMPORTANT NOTE: Don't forget to run autoconf in wxWidgets root directory + (after running Bakefile) if you changed any conditional + variable or target condition in .bkl files! You will know that + this happened if $(wx)/autoconf_inc.m4 content changed. + +You can use Bakefile to generate makefiles or projects customized to your +needs, too. See Bakefiles.bkgen for details on bakefile commands used to +generate makefiles. For example, you can use this command to generate +VC++ project files without wxUniversal configurations: + bakefile -v -fmsvc6prj -o../wxmy.dsw -DRUNTIME_LIBS=dynamic + -DDEBUG_INFO=default -DDEBUG_FLAG=default + -DOFFICIAL_BUILD=0 -DUSE_HTML=1 -DUSE_OPENGL=1 + -DMONOLITHIC=0 -DUSE_GUI=1 -DWXUNIV=0 wx.bkl +Or monolithic instead of multilib (the default): + bakefile -v -fmsvc6prj -o../wxmono.dsw -DRUNTIME_LIBS=dynamic + -DDEBUG_INFO=default -DDEBUG_FLAG=default + -DOFFICIAL_BUILD=0 -DUSE_HTML=1 -DUSE_OPENGL=1 + -DMONOLITHIC=1 -DUSE_GUI=1 wx.bkl +Or monolithic wxBase: + bakefile -v -fmsvc6prj -o../wxBase.dsw -DRUNTIME_LIBS=dynamic + -DDEBUG_INFO=default -DDEBUG_FLAG=default + -DOFFICIAL_BUILD=0 -DUSE_HTML=0 -DUSE_OPENGL=0 + -DMONOLITHIC=1 -DUSE_GUI=0 wx.bkl +It is, however, recommended to modify Bakefiles.bkgen (or +Bakefiles.local.bkgen) by means of and directives +and use bakefile_gen instead of running bakefile directly. + + +2. Bakefile files organization +------------------------------ + +Makefile are generated from .bkl files ("bakefiles") from two places: + - $(wx)/build/bakefiles directory + - samples directories +$(wx)/build/bakefiles contains bakefiles for main library and support files +that simplify writing bakefiles for samples. + +Support files are: + wxwin.py - helper functions + common.bkl + common_samples.bkl + config.bkl - user-configurable build options + make_dist.mk - implementation of "make dist" on Unix + +Files used to build the library are: + wx.bkl - main file + files.bkl - lists of source files + monolithic.bkl - targets for wxWin built as single big library + multilib.bkl - targets for multilib build + opengl.bkl - GL library with wxGLCanvas (this one is not + included in monolithic library for historical + reasons, so "monolithic" really means "two libs") + {expat,jpeg,png,tiff, + regex,zlib,odbc}.bkl - 3rd party libraries makefiles + + +3. Adding files to existing library +----------------------------------- + +UPDATE: files.bkl is now itself partially generated from the master file + build/files. If the variable which you need to modify, according to the + instructions below, is already defined in build/files, update it there + and run build/upmake to update files.bkl. + + +All files used by main libraries are listed in files.bkl. The file is +organized into variables for toolkits, platforms and libraries. The variables +come in pairs: there's always FOO_SRC for source files and FOO_HDR for header +files. Platform or toolkit specific files are grouped together in variable +with platform or toolkit name in them, e.g. BASE_WIN32_SRC, BASE_UNIX_SRC, +GTK_SRC, MOTIF_SRC. + +Note: A side effect of this toolkit-centric organization is that one file may + be present several times in files.bkl in different contexts. + +When you are adding a file, you must put it into appropriate variable. This is +easy if you are adding the file to library that is always built from same +sources on all platforms (e.g. wxXml or wxXML) -- simply add the file to e.g. +HTML_SRC or HTML_HDR. + +If the file is used only on one platform and is part of wxBase, add it to +BASE_{platform}_SRC/HDR. If it is used on all platforms, add it to BASE_CMN. +If it is built on more than one platform but not on all of them, add the file +to *all platforms that use it*! + +If a file is not wxBase file, but GUI file, then the variables are named after +toolkits/ports, not platforms. Same rules as for wxBase files apply +(substitute "platform" with "toolkit"). Make sure you correctly choose between +{port}_LOWLEVEL_SRC and {port}_SRC -- the former is for files used by +wxUniversal, e.g. GDI classes. Files shared by all X Window System ports +should be put into XWIN_LOWLEVEL_SRC. + + +4. Adding sample +---------------- + +Copy the bakefile from another sample, change the ID and files accordingly. +If the sample uses some data files, make sure to have node +in the sample's bakefile (see e.g. samples/image/image.bkl for an example). +Make sure to add statements for all libraries from multilib build +that are required by the sample. + +The Windows resource specification should use the central .rc file: + + ../sample.rc + +Run bakefile_gen in $(wx)/build/bakefiles to regenerate the bakefiles. + +Finally commit $(wx)/build/bakefiles/make_dist.mk and all the other modified files. + +Currently we commit the generated makefiles except .dms, .vcp. + + +5. Adding new core library +-------------------------- + +When adding new library to the core set of libraries, the files must be +added to both a newly added library in multilib build and into the single +library built in monolithic mode. We will assume that the new library is +called wxFoo. + +a) Add files to files.bkl: + * If wxFoo builds from same files on all platforms (e.g. wxNet), + add FOO_SRC and FOO_HDR variables with lists of sources and headers. + * If wxFoo have no files in common (e.g. wxGL), add FOO_SRC and FOO_HDR + with toolkit or platform conditions. Have a look at OPENGL_SRC for an + example. + * Otherwise add FOO_CMN_SRC and FOO_CMN_HDR for common files and + FOO_{platform}_{SRC,HDR} or FOO_{toolkit}_{SRC,HDR} as appropriate. Add + FOO_PLATFORM_{SRC,HDR} into "Define sources for specific libraries" + section that is conditionally set to one of FOO_xxx_{SRC,HDR} based on + target platform/toolkit (see NET_PLATFORM_SRC definition for an example). + Finally, define FOO_SRC and FOO_HDR to contain both + FOO_PLATFORM_{SRC,HDR} and FOO_{SRC,HDR} (see NET_SRC definition for an + example). + * Add FOO_HDR to ALL_GUI_HEADERS or ALL_BASE_HEADERS. + * If wxFoo is wxBase library (doesn't use GUI), add FOO_SRC to + ALL_BASE_SOURCES. + + (You can apply different approaches to HDR and SRC variables, if e.g. + headers are all common but sources are not.) + + Note that the conditions can only test for equality, due to limitations of + native make tools. + +b) Modify bakefile system in build/bakefiles/ to recognize wxFoo: + * Add 'foo' to MAIN_LIBS and LIBS_NOGUI or LIBS_GUI (depending on whether + the library depends on wxCore or not) to wxwin.py file. + * Add extra libraries needed by wxFoo (if any) to EXTRALIBS in wxwin.py + * Add WXLIB_FOO definition to common.bkl (into the "Names of component + libraries" section). It looks like this: + + $(mk.evalExpr(wxwin.mkLibName('foo'))) + + +c) Modify monolithic.bkl to add files to monolithic build: it's enough to add + FOO_SRC to MONOLIB_GUI_SRC or MONOLIB_SRC, depending on whether wxFoo uses + GUI or not. + +d) Modify multilib.bkl to add files to multilib build: add foolib and foodll + targets. Don't use wxBase targets as the template, use e.g. wxXML or wxHTML. + Make sure WXMAKINGDLL_FOO is defined in foodll. + +e) Regenerate all makefiles (don't forget to run autoconf) + +f) Update configure.in and wx-config.in to contain information about + the library and needed linker flags: + * Add "foo" to BUILT_WX_LIBS in configure.in. + * If appropriate, but it rarely is, so normally this should _not_ be done, + add "foo" to either STD_BASE_LIBS or STD_GUI_LIBS in configure.in. + * If wxFoo links against additional libraries, add necessary linker + flags and libraries to ldflags_foo and ldlibs_foo variables in + wx-config.in (both are optional). + +g) Update dlimpexp.h to define WXMAKINGDLL_FOO if WXMAKINGDLL is defined (add + #define WXMAKINGDLL_FOO inside first "#ifdef WXMAKINGDLL" block in + dlimpexp.h) and to define WXDLLIMPEXP_FOO and WXDLLIMPEXP_DATA_FOO. You + can copy e.g. WXDLLIMPEXP_NET definition, it is something like this: + #ifdef WXMAKINGDLL_NET + #define WXDLLIMPEXP_NET WXEXPORT + #define WXDLLIMPEXP_DATA_NET(type) WXEXPORT type + #elif defined(WXUSINGDLL) + #define WXDLLIMPEXP_NET WXIMPORT + #define WXDLLIMPEXP_DATA_NET(type) WXIMPORT type + #else // not making nor using DLL + #define WXDLLIMPEXP_NET + #define WXDLLIMPEXP_DATA_NET(type) type + #endif + Don't forget to add WXDLLIMPEXP_FWD_FOO definitions too. + Use WXDLLIMPEXP_FOO when declaring wxFoo classes and functions. + +h) Add this code to one of wxFoo's files (the more often used, the better): + // DLL options compatibility check: + #include "wx/app.h" + WX_CHECK_BUILD_OPTIONS("wxFoo") + +i) Add information about wxFoo to the manual ("Libraries list" section + in libs.tex) and update docs/latex/wx/libs.dia (you need Dia for this) + to show the dependencies of the new library. + +j) Also please add 4 #pragma comment(lib, "foo") (for Unicode/ANSI + Release/Debug combinations) to the file include/msvc/wx/setup.h and + add a check for WXMAKINGDLL_FOO to the test whether we're building a DLL at + the end of include/wx/msw/chkconf.h. + +=== EOF === + diff --git a/docs/contributing/how-to-add-new-font-encoding.txt b/docs/contributing/how-to-add-new-font-encoding.txt new file mode 100644 index 0000000000..86f8a16212 --- /dev/null +++ b/docs/contributing/how-to-add-new-font-encoding.txt @@ -0,0 +1,67 @@ + How to add a new font encoding to wxWidgets + =========================================== + +I. Introduction +--------------- + + wxWidgets has built in support for a certain number of font encodings (which +is synonymous with code sets and character sets for us here even though it is +not exactly the same thing), look at include/wx/fontenc.h for the full list. +This list is far from being exhaustive though and if you have enough knowledge +about an encoding to add support for it to wxWidgets, this tech note is for +you! + + A word of warning though: this is written out of my head and is surely +incomplete. Please correct the text here, especially if you detect problems +when you try following it. + + Also note that I completely ignore all the difficult issues of support for +non European languages in the GUI (i.e. BiDi and text orientation support). + + +II. The receipt +--------------- + +Suppose you want to add support for Klingon to wxWidgets. This is what you'd +have to do: + +1. include/wx/fontenc.h: add a new wxFONTENCODING_KLINGON enum element, if + possible without changing the values of the existing elements of the enum + and be careful to now make it equal to some other elements -- this means + that you have to put it before wxFONTENCODING_MAX + +2. wxFONTENCODING_MAX must be the same as the number of elements in 3 + (hopefully) self explanatory arrays in src/common/fmapbase.cpp: + a) gs_encodings + b) gs_encodingDescs + c) gs_encodingNames + + You must update all of them, e.g. you'd add wxFONTENCODING_KLINGON, + "Klingon (Star Trek)" and "klingon" to them in this example. The latter + name should ideally be understandable to both Win32 and iconv as it is used + to convert to/from this encoding under Windows and Unix respectively. + Typically any reasonable name will be supported by iconv, if unsure run + "iconv -l" on your favourite Unix system. For the list of charsets + supported under Win32, look under HKEY_CLASSES_ROOT\MIME\Database\Charset + in regedit. Of course, being consistent with the existing encoding names + wouldn't hurt neither. + +3. Normally you don't have to do anything else if you've got support for this + encoding under both Win32 and Unix. If you haven't, you should modify + wxEncodingConverter to support it (this could be useful anyhow as a + fallback for systems where iconv is unavailable). To do it you must: + a) add a new table to src/common/unictabl.inc: note that this file is auto + generated so you have to modify misc/unictabl script instead (probably) + b) possibly update EquivalentEncodings table in src/common/encconv.cpp + if wxFONTENCODING_KLINGON can be converted into another one + (losslessly only or not?) + +4. Add a unit test (see tn0017.txt) for support of your new encoding (with + time we should have a wxCSConv unit test so you would just add a case to + it for wxFONTENCODING_KLINGON) and test everything on as many different + platforms as you can. + + +=== EOF === + +Author: VZ diff --git a/docs/contributing/how-to-add-new-sample.txt b/docs/contributing/how-to-add-new-sample.txt new file mode 100644 index 0000000000..72232cb164 --- /dev/null +++ b/docs/contributing/how-to-add-new-sample.txt @@ -0,0 +1,59 @@ + How to add a new sample to wxWidgets. + ===================================== + +To add a new sample "foo" under directory "samples/foo" you need to do +the following: (note that all this applies also to demos: just replace +samples/ with demos/ where needed). + +1. Create the directory samples/foo locally and "svn add" it. + +2. "svn add" the sample sources (usually based on minimal.cpp) as well. + + Note that unless your sample requires something special you shouldn't + add foo.rc, foo.ico, ... any more, please just reuse the generic sample.* + files in the samples subdirectory. + +3. Create the makefiles: + a) modify samples/samples.bkl (just copy an existing line) + b) create foo.bkl (sed 's/minimal/foo/g' minimal.bkl > foo.bkl is usually + enough, but you may need to add more lines if your sample uses + anything not in the core lib) + c) generate the makefiles for your sample using bakefile. For this you + need to: + (i) install bakefile (see http://bakefile.sf.net/) + (ii) run bakefile_gen in build/bakefiles which will regenerate all + makefiles which are not up to date + + You may also use "bakefile_gen -b ../../samples/foo/foo.bkl" to + regenerate only the makefiles for this sample (path must be relative!) + or even add a "-f" to generate just the makefiles for the given + compiler (run 'bakefile --help' to get the list of possible values). + See Technote #16 for more information. + d) currently samples/samples.dsw needs to be updated manually as it's not + generated by bakefile. + +4. Modify configure.in Unix compilation: + a) if the sample should only be built if "wxUSE_FOO" is enabled, locate + the test for "wxUSE_FOO = yes" in configure.in and add a line + SAMPLES_SUBDIRS="$SAMPLES_SUBDIRS foo" under it + b) if it should be always built, locate the line "if test $wxUSE_GUI = yes" + near the end of configure.in and modify the assignment to + SAMPLES_SUBDIRS to include "foo" (put in alphabetical order) + + After this, regenerate configure from configure.in + by running "autoconf" on a Unix system in the corresponding directory. + +5. Add a short description of what the sample does and how does it work + to the "samples overview" section in the wxWidgets manual. That section + lives in docs/doxygen/mainpages/samples.h; look at the descriptions for + other samples, if you are not familiar with Doxygen. + +6. Add any non-standard sample's files to build/bakefiles/make_dist.mk (the + makefiles copies all bmp, cpp, h, ico, png, rc, xpm and makefiles by + default, you only need to update it if the sample uses some other files) + and run the ./update-manifests.sh script in distrib/scripts (don't forget + to check the changes to manifests/*.rsp files in). + +=== EOF === + +Author: VZ diff --git a/docs/contributing/how-to-add-new-ui-bitmaps.txt b/docs/contributing/how-to-add-new-ui-bitmaps.txt new file mode 100644 index 0000000000..32f9d80e9c --- /dev/null +++ b/docs/contributing/how-to-add-new-ui-bitmaps.txt @@ -0,0 +1,120 @@ + How to add new bitmaps to wxWidgets UI elements + =============================================== + +0. Introduction +--------------- + +Since the introduction of wxArtProvider class, it is no longer desired to +hardcode art resources (e.g. icons and toolbar or button bitmaps) into the +code. This was previously done either by including the bitmap in win32 +resource file (include/wx/msw/wx.rc) or by including XPM files in the code. + +wxArtProvider should be used instead, to allow users to customize the look of +their wxWidgets app. This technote is a detailed description of steps needed +when adding new bitmap/icon. + +1. Adding new resource +---------------------- + +(Please see wxArtProvider reference documentation for explanation of "art ID" + and "art client" terms.) + +First of all, you have to add new wxArtID constant to include/wx/artprov.h. +Look for "Art IDs" and add new definition to the list, e.g. + #define wxART_MY_BITMAP wxART_MAKE_ART_ID(wxART_MY_BITMAP) + +Add it to interface/wx/artprov.h, too. + +It may happen that the intended use of the new resource doesn't fit into any +of defined client categories (search for "Art clients" in the header). In case +the new resource is part of a larger category, you need to define a new +client. Just add it to the list of existing clients (and don't forget to +update artprov.tex): + #define wxART_MY_CLIENT wxART_MAKE_CLIENT_ID(wxART_MY_CLIENT) + +Alternatively, you may use wxART_OTHER when accessing the resource if the +bitmap is standalone. + +Once the header is updated, it's time to add XPM file with the bitmap to +$(wx)/art. Add it to $(wx)/art if it is platform-independent or to +$(wx)/art/$(toolkit) if it is something specific to one of the toolkits. Note +that "specific to one of the toolkits" doesn't mean that the bitmap is *used* +by only one toolkit, but that it doesn't make sense for any of the others! For +example, a GTK wxART_WARNING icon ($(wx)/art/gtk/warning.xpm) is specific to +wxGTK, but new_dir.xpm makes sense even under wxMSW even though it is +currently only used by the generic file dialog. Remember that wxArtProvider +can be used by users, not only the library. + +Finally, wxDefaultArtProvider in $(wx)/src/common/artstd.cpp must be updated. +This consists of two steps: + + a) add #include line for your XPM file, e.g. #include "../../art/my_bmp.xpm" + b) add ART(...) line to wxDefaultArtProvider::CreateBitmap(). The first + argument is wxArtID, the other is XPM file name (w/o extension), e.g. + ART(wxART_MY_BITMAP, my_bmp) + +That's all. The bitmap is now available to wxArtProvider users. + +Note: there's no difference between icons and bitmaps, always treat them as +bitmaps inside wx(Default)ArtProvider. + +1b. Adding Tango version of the resource. +----------------------------------------- + +While all the bitmaps are provided in XPM format so that they are available in +all builds of wxWidgets, we also provide most of them in PNG format with full +transparency support that is not available in XPM. Another advantage of the PNG +versions is that the icons used are those of the Tango project and so have the +consistent look, unlike the XPM ones. + +So if you an icon exists in http://tango.freedesktop.org/Tango_Icon_Gallery you +should add it too. For this you need to: + +1. Convert the PNG to a C array of bytes suitable for inclusion in the code. + This is done using misc/scripts/png2c.py script, e.g. if the variable "f" + contains the name of the icon you want to add and you have installed Tango + icons in a standard location under a Linux system: + + ./misc/scripts/png2c.py -s /usr/share/icons/Tango/{16x16,24x24}/*/$f.png > + art/tango/${f//-/_}.h + + Of course, the same command may be ran with different paths under Windows. + Just remember to add both 16 and 24 pixel versions of the bitmap to the + header and use the "-s" option to embed the image size in its array name. + +2. Add #include for the newly created file to src/common/arttango.cpp. + +3. Add an entry to s_allBitmaps array in the same file. + + +2. Accessing the resource +------------------------- + +The file that will use the bitmap needs to include "wx/artprov.h". The code to +access the bitmap (or icon) is trivial: + + wxBitmap bmp = wxArtProvider::GetBitmap(wxART_MY_BITMAP, wxART_MY_CLIENT); + // this would be "wxBitmap bmp(my_bmp_xpm);" before + wxIcon icon = wxArtProvider::GetIcon(wxART_MY_ICON, wxART_MY_CLIENT); + +Substitute wxART_MY_CLIENT in the example with a suitable client ID. If the +client is wxART_OTHER you may write only + + wxArtProvider::GetBitmap(wxART_MY_BITMAP). + +3. Providing a demo +------------------- + +It is highly desirable to let the users know what stock bitmaps are available +in wxWidgets. The "artprov" sample serves this purpose: it contains a browser +dialog that displays all available art resources. + +It has to be updated to accommodate for new bitmaps. Fortunately, this is +trivial: open $(wx)/samples/artprov/artbrows.cpp in text editor and +ART_ICON(wxART_MY_BITMAP) line to the FillBitmaps() function. + +Similarly, if you add a new client, please update FillClients() by adding new +client to the end of the list. + +=== EOF === + diff --git a/docs/contributing/how-to-add-new-wxUSE_XXX.txt b/docs/contributing/how-to-add-new-wxUSE_XXX.txt new file mode 100644 index 0000000000..1bd5cafb5e --- /dev/null +++ b/docs/contributing/how-to-add-new-wxUSE_XXX.txt @@ -0,0 +1,83 @@ + How to add a new wxUSE_XXX preprocessor constant + ================================================ + +0. Purpose +---------- + +Detailed description of what needs to be done when you want to add a new +wxUSE_XXX compilation flag. The text below assumes you need new wxUSE_FOO. + + +1. Overview +----------- + +wxWidgets uses wxUSE_XXX macros for conditionally compiling in (or not) +optional components. In general, whenever a new non critical (i.e. not +absolutely required by important parts of the library) class Foo is added it +should use its own wxUSE_FOO compilation flag. + +wxUSE_FOO must be always defined and have value of 0 or 1. Be careful with +testing for it in wx/foo.h: don't do it at the very beginning of the file +because then wxUSE_FOO would be not defined at all if the user directly +includes wx/foo.h, include "wx/defs.h" before testing for wxUSE_FOO. + + +2. Files to update +------------------ + +The following files need to be modified when adding a new wxUSE_FOO: + +a) include/wx/setup_inc.h + + This file contains all common wxUSE_XXXs, and is used to update wxMSW, wxMac + setup.h and Unix setup.h.in using build/update-setup-h. Please try to add + the new define in a logical place (i.e. near any related ones) and write a + detailed comment explaining what does it do and why would you want to turn + it on/off. Choose the appropriate default value: this should be usually 1 + but can be 0 if there are some problems preventing the use of Foo by default + (e.g. it requires installation of some non standard 3rd party libraries). + After changing this file, run the update-setup-h script (this is probably + better done on a Unix machine although it should work under Cygwin too). + +a') include/wx/msw/setup_inc.h for MSW-specific options + + This file contains MSW-specific options, so if the new option is only used + under MSW, add it here instead of include/wx/setup_inc.h. The rest of the + instructions is the same as above. + +b) include/wx/chkconf.h + + Add the check for wxUSE_FOO definedness in the corresponding (base or GUI) + section. Please keep the alphabetic order. + + If there are any dependencies, i.e. wxUSE_FOO requires wxUSE_BAR and + wxUSE_BAZ, check for thme here too. + +b') include/wx/msw/chkconf.h for MSW-specific options + + These options won't be defined for the other ports, so shouldn't be added to + the common include/wx/chkconf.h but to this file instead. + +c) configure.in + + Here you need to add DEFAULT_wxUSE_FOO define. It should be added in the + block beginning after WX_ARG_CACHE_INIT line and should default to "no" for + "if DEBUG_CONFIGURE = 1" branch (this is used for absolutely minimal builds) + and the same as default value in setup_inc.h in the "else" branch. + + You also need to add a WX_ARG_ENABLE (or, if new functionality can be + reasonably described as support for a 3rd party library, WX_ARG_WITH) + line togetherw with all the existing WX_ARG_ENABLEs. + + If you have a sample/foo which should be only built when wxUSE_FOO==1, + then only add it to the SAMPLES_SUBDIRS if wxUSE_FOO=yes in configure. + +d) docs/doxygen/mainpages/const_wxusedef.h + + Add a brief description of the new constant. + + +=== EOF === + +Author: VZ + diff --git a/docs/contributing/how-to-add-new-xrc-handler.txt b/docs/contributing/how-to-add-new-xrc-handler.txt new file mode 100644 index 0000000000..d724d5efbb --- /dev/null +++ b/docs/contributing/how-to-add-new-xrc-handler.txt @@ -0,0 +1,54 @@ + How to add a new XRC handler + ============================ + +0. Purpose +---------- + +This note describes what needs to be done to add a new XRC handler, i.e. add +support for loading the objects of some class wxFoo from XRC. + + +1. Implement the handler +------------------------ + +By convention, the XRC handler for a class wxFoo declared in wx/foo.h is called +wxFooXmlHandler and is declared in the file wx/xrc/xh_foo.h (this last rule +wasn't always respected in the past, however it's not a reason to not respect +it in the future). The steps for adding a new handler are: + +a) Add handler declaration in include/wx/xrc/xh_foo.h, it will usually be the + same as in the other files so you can get inspiration for your brand new + handler from e.g. wx/xrc/xh_srchctrl.h. Notice the use of wxUSE_FOO if wxFoo + is guarded by this symbol. + +b) Add implementation in src/xrc/xh_foo.cpp: again, it will be almost always + very similar to the existing controls. You will need to add support for + the control-specific styles. + + +2. Update the other files +------------------------- + +There are a few other files to update to make wxWidgets aware of the new +handler: + +a) Add the new files created above to build/bakefiles/files.bkl: search for + "xh_srchctrl" to see where you need to add them + +b) Add #include "wx/xrc/xh_foo.h" to wx/xrc/xh_all.h. + +c) Register the new handler in wxXmlResource::InitAllHandlers() in + src/xrc/xmlrsall.cpp + + +3. Update the sample +-------------------- + +Demonstrate that the new handler works by adding a control using it to +samples/xrc/rc/controls.xrc. + + +=== EOF === + +Author: VZ + diff --git a/docs/contributing/how-to-release.txt b/docs/contributing/how-to-release.txt new file mode 100644 index 0000000000..7cccd99349 --- /dev/null +++ b/docs/contributing/how-to-release.txt @@ -0,0 +1,180 @@ + Making a new wxWidgets release + ============================== + +Before making the release +------------------------- + +Change the version in include/wx/version.h. + +Update docs/readme.txt. Please review its contents in addition to just +changing the version number. + +Put a date on the release line in docs/changes.txt. + +Update the date in the manual (docs/doxygen/mainpages/manual.h). + +Update the release announcement post in docs/publicity/announce.txt. + + +Creating release files +---------------------- + +The currently used release scripts need to be used from git-svn checkout and +rely on Git to avoid problems with using non-clean trees and such. If you don't +use Git you may use the alternative archive creation scripts in the next +section. + +Follow these steps assuming the current working directory is the root of git +working copy and you want to prepare distribution for the version x.y.z: + +1. Run "./build/tools/svn-find-native-eols.pl > ../eol-native" (if you have + an existing svn checkout, pass it to the script to make it run much faster, + but take care to have up to date sources in the working tree). + +2. Run "./build/tools/git-make-release x.y.z" to create source archives + ../wxWidgets-x.y.z.{7z,tar.bz2,zip} and wxWidgets_x.y.z_Headers.zip. + +3. Run "./build/tools/make-html-docs x.y.z" to create HTML documentation + archives ../wxWidgets-x.y.z.{tar.bz2,zip} + +4. This step must be done under Windows as it relies on having hhc.exe, the + Html Help compiler, in PATH: run the following commands + + cd docs\doxygen + regen.bat chm + cd out + zip ..\..\..\wxWidgets-x.y.z-docs-chm.zip wx.chm + +5. This step also must be done under Windows as it uses Inno Setup to produce + the .exe file and it also requires the CHM file built above: + + md x.y.z-sources + cd x.y.z-sources + 7z x ..\wxWidgets-x.y.z.7z + md docs\htmlhelp + cp ..\docs\doxygen\out\wx.chm docs\htmlhelp + set WXW_VER=x.y.z + iscc build\tools\wxwidgets.iss + + + +Instructions for the previous version of release scripts +-------------------------------------------------------- + +NB: These scripts haven't been used since 2.8 series and may not work any longer! + +Currently our release system uses a Python 2.x script to generate releases. +The script requires Unix utilities such as tar, zip and unix2dos and thus must +be run either on Unix or using Cygwin on Windows. To generate a release, simply +run the following command: + +build/tools/create-archive.py --compression=all /path/to/output/dir + +This will produce zip, gzip and bzip archives of the tree (without +"compression" argument only .gz is made). Note that this commands produces huge +amounts of output so redirecting it to a file is recommended. + +To add a prefix to the release, such as RC1, the SVN revision, or a date, just +pass --postfix="postfix" to the script. More info on the options and their +possible values can be found by calling `create-archive.py --help`. + +IMPORTANT NOTE: You *must* run this script from a clean source tree, that is, + with no junk files in it or modifications. This is because the + release should be a pristine copy of the tree as of the time of + release. If you have legitimate modifications in the tree that need + to be in the release, commit them first. + +To generate the windows installer (.exe) and the documentation files (chm and htb formats) +run: + +build\tools\bld_chm_exe.bat + +which depends on the wxwidgets.iss file, and generates output in the %DAILY% directory. It +assumes a clean copy of the wxWidgets source tree in %INNO%. Temporary files will be generated +in the tree from which the batch file is run. It depends on doxygen, a number of gnu +win32 tools and Microsofts htmlhelp compiler. The wxwidgets.iss file should not need +editing, but you will want to check that the bld_chm_exe.bat has the correct version number. + + + +Uploading +--------- + +Upload the files to SourceForge. This can be done via the web interface or just +scp to sfusername,wxwindows@frs.sf.net:/home/frs/project/w/wx/wxwindows/x.y.z +The following files need to be uploaded: + + wxMSW-Setup-x.y.z.exe + wxWidgets-x.y.z.7z + wxWidgets-x.y.z.tar.bz2 + wxWidgets-x.y.z.zip + wxWidgets-docs-chm-x.y.z.zip + wxWidgets-docs-html-x.y.z.tar.bz2 + wxWidgets-docs-html-x.y.z.zip + +The file wxWidgets-x.y.z_Headers.7z should be uploaded to binaries +subdirectory as it's only useful when using pre-built binaries. + +You will need to use the web interface to mark the latest uploaded files as +being "default downloads" for the appropriate platforms (.zip or .exe for MSW, +.tar.bz2 for everything else) as otherwise SourceForge would continue to suggest +people to download old files. + +Next, update (at least the versions and SHA1 sums, but maybe more) and upload +docs/release_files.mdwn and docs/release_binaries.mdwn files. They need to be +renamed to README.md on SF to be shown when the directory is viewed, i.e. do: + + scp docs/release_files.mdwn \ + sfuser,wxwindows@frs.sf.net:/home/frs/project/w/wx/wxwindows/x.y.z/README.md + scp docs/release_binaries.mdwn \ + sfuser,wxwindows@frs.sf.net:/home/frs/project/w/wx/wxwindows/x.y.z/binaries/README.md + +And upload the change log too: + + scp docs/changes.txt \ + sfuser,wxwindows@frs.sf.net:/home/frs/project/w/wx/wxwindows/x.y.z + + +Also upload the files to the FTP mirror at ftp.wxwidgets.org (ask Chris for +access if you don't have it). + +Create http://docs.wxwidgets.org/x.y.z/ (ask Bryan to do it if not done yet). + + +Announcement +------------ + +Post docs/publicity/announce.txt at least to wx-announce@googlegroups.com and +to wx-users for the important releases. + +Submit a link to http://www.reddit.com/r/programming + +Submit to http://isocpp.org/blog/suggest + +For major releases, submit the announcement to http://slashdot.org/submission + +Update www.wxwidgets.org, usually a news item is enough but something more can +be called for for major releases. + +Modify the links at downloads/index.html to point to the new release. + +Also update docs/index.html for the minor or major (i.e. not micro) releases. + +Post to wxBlog if necessary. + +Announce on Google+/Twitter/whatever the person doing the release prefers (we +don't have "official" wxWidgets account, should we?). + + +Version updates +--------------- + +Trac: mark the milestone corresponding to the release as completed and add a +new version for it to allow reporting bugs against it and create the next +milestone (ask Vadim or Robin to do it or to get admin password). + +Run misc/scripts/inc_release to increment micro version, i.e. replace x.y.z +with x.y.z+1 (minor or major versions updates require manual intervention). + +Update the definition of the stable and release branches in +build/buildbot/config/include/defs.xml after a minor version change. diff --git a/docs/contributing/how-to-update-third-party-library.txt b/docs/contributing/how-to-update-third-party-library.txt new file mode 100644 index 0000000000..058084a9c1 --- /dev/null +++ b/docs/contributing/how-to-update-third-party-library.txt @@ -0,0 +1,127 @@ + How to update a third party library to a newer version + ====================================================== + +0. Introduction +--------------- + +wxWidgets includes several third party libraries, i.e. libraries which are +used by wxWidgets and distributed with it but which we don't maintain nor even +modify, inasmuch as possible, ourselves. These libraries are developed by +their maintainers and from time to time we need to replace the versions used +by wxWidgets with newer versions. + + +1. Vendor branches +------------------ + +Normally all third party libraries should be managed using Subversion vendor +branches. I.e. we should have the latest version of the library under +/wx/wxWidgets/vendor directory in the repository. Currently only expat, libpng +and libtiff are handled like this, while libjpeg and zlib are not. Hopefully +these exceptions will disappear soon, the rest of this note assumes that we +are using a vendor branch for the library $(LIB). + +We also use $(OLD_VERSION) and $(VERSION) below for the current version of the +library and the version we are upgrading to. $(OLD_VERSION) can be determined +by doing + + svn ls https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB) + +as normally it's the latest version present in this directory. You can, of +course, also look at the library sources currently in the trunk to find out +its version. + + +NB: the instructions here are based on the Subversion documentation, see +http://svnbook.red-bean.com/en/1.6/svn.advanced.vendorbr.html for more +information about vendor branches. + + +2. Updating the current branch +------------------------------ + +The first thing to do is to checkout a pristine copy of the version currently +being used, e.g. + + cd /some/temp/directory + svn checkout https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB)/current $(LIB) + +Now delete all the old files: + + cd $(LIB) + find . -type f -not -path '*/.svn/*' -exec rm {} \; + +or, if you are using zsh, just + + rm **/*(.) + +Next, get the version of the library you are updating to and unpack it into +the same directory. Examine "svn status" output and add all the files with "?" +in the first column using "svn add" and delete all the files with "!" in the +first column using "svn rm". + +Finally commit and tag the new version: + + svn commit -m 'Update $(LIB) to $(VERSION).' + svn cp https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB)/current \ + https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB)/$(VERSION) \ + -m 'Tagging $(LIB) $(VERSION).' + +You can now do + + rm -rf /some/temp/directory/$(LIB) + +as it won't be needed any longer. + + +3. Merging the current branch +----------------------------- + +Now switch to wxWidgets checkout and run + + svn merge ^/wxWidgets/vendor/$(LIB)/$(OLD_VERSION) ^/wxWidgets/vendor/$(LIB)/current src/$(LIBDIR) + +Notice that you may need to escape the circumflexes with backslashes if they +are special for your shell. Also notice that the directory of the library may +be different from its name, e.g. we use libpng for the vendor branch but just +png for the name of the directory. + +Unless you are very lucky, the merge will result in conflicts and you will +need to resolve them by examining the differences -- this is the difficult +part. + +Once everything was resolved, test your changes. As building the third party +libraries is quite different between Unix and Windows, please do it under both +platforms. Under Windows it's enough to just build everything as usual as the +built-in libraries are used by default. Please build both static and dynamic +wxWidgets libraries as some problems arise only in one of those configurations. +Under Unix you need to configure with --with-$(LIB)=builtin option to ensure +that the newly updated built-in version of the library is used and not the +system version. If upgrading an image format library, please build and run the +image sample. In any case, run the unit tests to check that everything still +works. + +After testing and correcting the problems, simply commit your changes: + + svn commit -m 'Update $(LIB) to $(VERSION).' src/$(LIBDIR) + + +4. Special instructions for libpng +---------------------------------- + +We use a special hack for libpng as we want to prefix all its symbols with +"wx_" but don't want to use its build system which makes this easily possible +(perhaps we should, but for now we don't). So, when upgrading libpng, you need +to perform an extra step after merging the new version (and before committing +your changes): + +Create a temporary build directory and run libpng configure from it using +--with-libpng-prefix=wx_ option. Then run "make" (actually just "make png.lo" +is sufficient as we don't really need to build the library) to create +pnglibconf.h and pngprefix.h files in the build directory. And copy these +files to src/png subdirectory of the wxWidgets source tree, overwriting the +versions there. + +Notice that config.h generated by libpng configure is not used, we build it +without -DHAVE_CONFIG_H as it works just fine without it on any ANSI C system +(i.e. anywhere by now). diff --git a/docs/contributing/how-to-write-unit-tests.txt b/docs/contributing/how-to-write-unit-tests.txt new file mode 100644 index 0000000000..94012357f9 --- /dev/null +++ b/docs/contributing/how-to-write-unit-tests.txt @@ -0,0 +1,144 @@ + How to write unit tests for wxWidgets + ===================================== + +Unit tests for wxWidgets are written using small cppunit framework. To compile +(but not to run) them you need to have it installed. Hence the first part of +this note explains how to do it while the second one explains how to write the +test. + +I. CppUnit Installation +----------------------- + +1. Get it from http://www.sourceforge.net/projects/cppunit + (latest version as of the time of this writing is 1.10.2) + +2. Build the library: + a) Under Windows using VC++: + - build everything in CppUnitLibraries.dsw work space + - add include and lib subdirectories of the directory + where you installed cppunit to the compiler search path + using "Tools|Options" menu in VC IDE + + b) Under Unix: run configure && make && make install as usual + + +II. Writing tests with CppUnit +------------------------------ + +1. Create a new directory tests/foo + +2. Write a cpp file for the test copying, if you want, + from one of the existing tests. The things to look for: + a) #include "wx/cppunit.h" instead of directly including CppUnit headers + b) don't put too many things in one test case nor in one method of a test + case as it makes understanding what exactly failed harder later + c) 'register' your tests as follows so that the test program will find and + execute them: + + // register in the unnamed registry so that these tests are run by default + CPPUNIT_TEST_SUITE_REGISTRATION(MBConvTestCase); + + // also include in its own registry so that these tests can be run alone + CPPUNIT_TEST_SUITE_NAMED_REGISTRATION(MBConvTestCase, "MBConvTestCase"); + + Read CppUnit documentation for more. + d) wxUIActionSimulator can be used when user input is required, for example + clicking buttons or typing text. A simple example of this can be found + in controls/buttontest.cpp. After simulating some user input always + wxYield to allow event processing. When writing a test using + wxUIActionSimulator always add the test using WXUISIM_TEST rather than + CPPUNIT_TEST as then it won't run on unsupported platforms. The test itself + must also be wrapped in a #if wxUSE_UIACTIONSIMULATOR block. + e) There are a number of classes that are available to help with testing GUI + elements. Firstly throughout the test run there is a frame of type + wxTestableFrame that you can access through wxTheApp->GetTopWindow(). This + class adds two new functions, GetEventCount, which takes an optional + wxEventType. It then returns the number of events of that type that it has + received since the last call. Passing nothing returns the total number of + event received since the last call. Also there is OnEvent, which counts the + events based on type that are passed to it. To make it easy to count events + there is also a new class called EventCounter which takes a window and event + type and connects the window to the top level wxTestableFrame with the specific + event type. It disconnects again once it is out of scope. It simply reduces + the amount of typing required to count events. + +3. add a '' tag for your source file to tests/test.bkl. Make sure it's + in the correct section: the one starting '/poEdit/bin to your path (so it can find xgettext). + +2. A way to run a program recursively on an entire directory from the command + line: + + a) for Unix systems, this is done in locale/Makefile using the standard find + command and xargs which is installed on almost all modern Unices. If you + are unlucky enough to not have xargs, you can use the -exec option of find + instead. + + b) for Win32 systems you can use either Cygwin or MinGW. If you don't have + those it is less trivial: if you have 4DOS/4NT/bash, that's + fine, but you'd have to use some kind of "for /s" loop with the + command.com/cmd.exe. + +3. (at least read) access to the subversion is not necessary strictly speaking, but + will make things a lot easier for you and others. + + +Now a brief overview of the process of translations (please refer to GNU +gettext documentation for more details). It happens in several steps: + +1. the strings to translate are extracted from the C++ sources using xgettext + program into a wxstd.pot file which is a "text message catalog" + +2. this new wxstd.pot file (recreated each time some new text messages are added + to wxWidgets) is merged with existing translations in another .po file (for + example, de.po) and replaces this file (this is done using the program + msgmerge) + +3. the resulting .po file must be translated + +4. finally, msgformat must be run to produce a .mo file: "binary message catalog" + + +How does it happen in practice? There is a Makefile in the "locale" +directory which will do almost everything (except translations) for you. i.e. +just type "make lang.po" to create or update the message catalog for 'lang'. +Then edit the resulting lang.po and make sure that there are no empty or fuzzy +translations left (empty translations are the ones with msgstr "", fuzzy +translations are those which have the word "fuzzy" in a comment just above +them). Then type "make lang.mo" which will create the binary message catalog. + +Under Windows (If you don't have Cygwin or MinGW), you should execute the +commands manually, please have a look at Makefile to see what must be done. + +For platform specific translations, .po files such as 'locale/msw/it.po' can be +used to provide translations that override the usual ones in 'locale/it.po'. +The generated .mo files are then installed under the names such as 'wxmsw.mo' +alongside the generic 'wxstd.mo'. + +A new platform specific translation should be added to a section such as this +in wx.bkl: + + + $(SRCDIR)/locale/msw + wxmsw + it + $(LOCALEDIR) + + +=== EOF === + +Author: VZ + +$Log$ +Revision 1.7 2005/08/12 15:34:01 MW +Typo + +Revision 1.6 2005/08/12 15:29:47 MW +Translate '&Help' to '&' for italian Windows only + +Revision 1.5 2004/10/22 19:12:59 KH +*** empty log message *** + +Revision 1.4 2004/05/04 08:26:58 JS +Name change replacements + +Revision 1.3 2003/11/18 16:37:11 DS +Updated translation technote to mention Makefile usage under Windows. + +Revision 1.2 2002/07/03 15:01:26 VZ +typos and other doc corrections from Olly Betts (patch 573738) + +Revision 1.1 2000/03/07 10:53:53 VZ +technote about translations added + diff --git a/docs/contributing/wxmsw-contributor-guide.txt b/docs/contributing/wxmsw-contributor-guide.txt new file mode 100644 index 0000000000..011cb44739 --- /dev/null +++ b/docs/contributing/wxmsw-contributor-guide.txt @@ -0,0 +1,53 @@ + Special notes about writing wxMSW code + ====================================== + +0. Purpose +---------- + +This is just a collection of various notes which should be useful to anybody +working on wxMSW codebase, please feel free to add more here. + +This text assumes familiarity with both Windows programming and wxWidgets so it +doesn't cover any wxWidgets-wide issues not specific to Windows. + + +1. Windows headers wrappers +--------------------------- + +In no event should the Windows headers such as or be +included directly. So instead of #include <...> use "wx/msw/wrapwin.h" or +"wx/msw/wrapcctl.h". + +For convenience it is also possible to replace #include and + with #include "wx/msw/wrapcdlg.h" and wrapshl.h but this is less +vital. + +Also notice that many convenient (albeit undocumented) functions and classes +are declared in "wx/msw/private.h", please do become familiar with this file +contents and use the utility classes and functions from it instead of +duplicating their functionality (which can often be done only in exception +unsafe way). + + +2. Windows features checks +-------------------------- + +All checks of features not present in all Windows versions must be done both at +compile-time (because, even though we use maximal value for WINVER in our code, +some compilers come with headers too old to declare them) and at run-time +(because wxMSW applications should run everywhere). + +The functions wxGetWinVersion() (from wx/msw/private.h) and wxApp:: +GetComCtl32Version() should be used to check Windows and comctl32.dll versions +respectively. + +Any functions which may not be present in kernel32.dll/user32.dll/... in all +Windows versions should be resolved dynamically, i.e. using wxDynamicLibrary as +otherwise any wx application -- even not needing them at all -- would refuse to +start up on Windows versions not implementing the feature in question. As an +example, look at AlphaBlt()-related code in src/msw/dc.cpp. + + +=== EOF === + +Author: VZ diff --git a/docs/tech/index.txt b/docs/tech/index.txt index 58bd144572..3adafa578d 100644 --- a/docs/tech/index.txt +++ b/docs/tech/index.txt @@ -1,29 +1,31 @@ - All wxWidgets technical notes at a glance - ========================================= +All the files in this directory are obsolete (including this one) and are kept +just to avoid breaking the existing links to them, please refer to the files +with the corresponding name under docs/contributing instead: -tn0001.txt How to add a new sample -tn0002.txt wxWidgets translator guide -tn0003.txt Adding wxWidgets class documentation -tn0004.htm *** REMOVED *** (obsoleted by Bakefile changes) -tn0005.txt Adding a wxWidgets contribution -tn0006.txt *** REMOVED *** (obsoleted by tn0013.txt) -tn0007.txt *** REMOVED *** (obsoleted by Bakefile changes) -tn0008.htm *** REMOVED *** (included in the manual now) -tn0009.htm Creating and converting icons -tn0010.htm *** REMOVED *** (obsoleted by Bakefile changes) -tn0011.txt All about version numbers -tn0012.txt wxWidgets platform, toolkit and library names -tn0013.txt *** REMOVED *** (obsoleted by tn0022.txt) -tn0014.txt *** REMOVED *** (included in the manual now) -tn0015.txt How to add new bitmaps to wxWidgets UI elements -tn0016.txt How to add new files and libraries to wxWidgets build system (Bakefile) -tn0017.txt How to write unit tests for wxWidgets classes -tn0018.txt How to add a new font encoding/charset to wxWidgets -tn0019.txt Special notes about writing wxMSW code -tn0020.txt Binary compatibility and wxWidgets -tn0021.txt How to add a new wxUSE_XXX preprocessor constant -tn0022.txt Making a new release -tn0023.txt Adding a new app/screenshot to the wxWidgets.org front page -tn0024.txt How to add a new XRC handler -tn0025.txt How to update a third party library to a newer version + +tn0001.txt -> docs/contributing/how-to-add-new-sample.txt +tn0002.txt -> docs/contributing/translators-guide.txt +tn0003.txt -> docs/contributing/how-to-add-class-documentation.txt +tn0004.htm -> *** REMOVED *** (obsoleted by Bakefile changes) +tn0005.txt -> *** REMOVED *** (obsoleted by http://wiki.wxwidgets.org/Development:_How_To_Contribute) +tn0006.txt -> *** REMOVED *** (obsoleted by tn0013.txt) +tn0007.txt -> *** REMOVED *** (obsoleted by Bakefile changes) +tn0008.htm -> *** REMOVED *** (included in the manual now) +tn0009.htm -> *** REMOVED *** (use any standard tool for icon creation) +tn0010.htm -> *** REMOVED *** (obsoleted by Bakefile changes) +tn0011.txt -> docs/contributing/about-version-numbers.txt +tn0012.txt -> docs/contributing/about-platform-toolkit-and-library-names.txt +tn0013.txt -> *** REMOVED *** (obsoleted by tn0022.txt) +tn0014.txt -> *** REMOVED *** (included in the manual now) +tn0015.txt -> docs/contributing/how-to-add-new-ui-bitmaps.txt +tn0016.txt -> docs/contributing/how-to-add-files-to-build-system.txt +tn0017.txt -> docs/contributing/how-to-write-unit-tests.txt +tn0018.txt -> docs/contributing/how-to-add-new-font-encoding.txt +tn0019.txt -> docs/contributing/wxmsw-contributor-guide.txt +tn0020.txt -> docs/contributing/binary-compatibility.txt +tn0021.txt -> docs/contributing/how-to-add-new-wxUSE_XXX.txt +tn0022.txt -> docs/contributing/how-to-release.txt +tn0023.txt -> *** REMOVED *** (obsoleted by web site redesign) +tn0024.txt -> docs/contributing/how-to-add-new-xrc-handler.txt +tn0025.txt -> docs/contributing/how-to-update-third-party-library.txt diff --git a/docs/tech/tn0001.txt b/docs/tech/tn0001.txt index 72232cb164..03cb9b9653 100644 --- a/docs/tech/tn0001.txt +++ b/docs/tech/tn0001.txt @@ -1,59 +1 @@ - How to add a new sample to wxWidgets. - ===================================== - -To add a new sample "foo" under directory "samples/foo" you need to do -the following: (note that all this applies also to demos: just replace -samples/ with demos/ where needed). - -1. Create the directory samples/foo locally and "svn add" it. - -2. "svn add" the sample sources (usually based on minimal.cpp) as well. - - Note that unless your sample requires something special you shouldn't - add foo.rc, foo.ico, ... any more, please just reuse the generic sample.* - files in the samples subdirectory. - -3. Create the makefiles: - a) modify samples/samples.bkl (just copy an existing line) - b) create foo.bkl (sed 's/minimal/foo/g' minimal.bkl > foo.bkl is usually - enough, but you may need to add more lines if your sample uses - anything not in the core lib) - c) generate the makefiles for your sample using bakefile. For this you - need to: - (i) install bakefile (see http://bakefile.sf.net/) - (ii) run bakefile_gen in build/bakefiles which will regenerate all - makefiles which are not up to date - - You may also use "bakefile_gen -b ../../samples/foo/foo.bkl" to - regenerate only the makefiles for this sample (path must be relative!) - or even add a "-f" to generate just the makefiles for the given - compiler (run 'bakefile --help' to get the list of possible values). - See Technote #16 for more information. - d) currently samples/samples.dsw needs to be updated manually as it's not - generated by bakefile. - -4. Modify configure.in Unix compilation: - a) if the sample should only be built if "wxUSE_FOO" is enabled, locate - the test for "wxUSE_FOO = yes" in configure.in and add a line - SAMPLES_SUBDIRS="$SAMPLES_SUBDIRS foo" under it - b) if it should be always built, locate the line "if test $wxUSE_GUI = yes" - near the end of configure.in and modify the assignment to - SAMPLES_SUBDIRS to include "foo" (put in alphabetical order) - - After this, regenerate configure from configure.in - by running "autoconf" on a Unix system in the corresponding directory. - -5. Add a short description of what the sample does and how does it work - to the "samples overview" section in the wxWidgets manual. That section - lives in docs/doxygen/mainpages/samples.h; look at the descriptions for - other samples, if you are not familiar with Doxygen. - -6. Add any non-standard sample's files to build/bakefiles/make_dist.mk (the - makefiles copies all bmp, cpp, h, ico, png, rc, xpm and makefiles by - default, you only need to update it if the sample uses some other files) - and run the ./update-manifests.sh script in distrib/scripts (don't forget - to check the changes to manifests/*.rsp files in). - -=== EOF === - -Author: VZ +Please see index.txt diff --git a/docs/tech/tn0002.txt b/docs/tech/tn0002.txt index 3680436ca3..03cb9b9653 100644 --- a/docs/tech/tn0002.txt +++ b/docs/tech/tn0002.txt @@ -1,102 +1 @@ - wxWidgets translator guide - ========================== - -This note is addressed to wxWidgets translators. - -First of all, here is what you will need: - -1. GNU gettext package version 0.10.35 or later (NB: earlier versions were - known to have serious bugs) - - a) for Unix systems you can download gettext-0.10.tar.gz from any GNU - mirror (RPMs and DEBs are also available from the usual places) - - b) for Windows you can download the precompiled binaries from - www.wxwidgets.org or install PoEdit (poedit.sourceforge.net) and - add /poEdit/bin to your path (so it can find xgettext). - -2. A way to run a program recursively on an entire directory from the command - line: - - a) for Unix systems, this is done in locale/Makefile using the standard find - command and xargs which is installed on almost all modern Unices. If you - are unlucky enough to not have xargs, you can use the -exec option of find - instead. - - b) for Win32 systems you can use either Cygwin or MinGW. If you don't have - those it is less trivial: if you have 4DOS/4NT/bash, that's - fine, but you'd have to use some kind of "for /s" loop with the - command.com/cmd.exe. - -3. (at least read) access to the subversion is not necessary strictly speaking, but - will make things a lot easier for you and others. - - -Now a brief overview of the process of translations (please refer to GNU -gettext documentation for more details). It happens in several steps: - -1. the strings to translate are extracted from the C++ sources using xgettext - program into a wxstd.pot file which is a "text message catalog" - -2. this new wxstd.pot file (recreated each time some new text messages are added - to wxWidgets) is merged with existing translations in another .po file (for - example, de.po) and replaces this file (this is done using the program - msgmerge) - -3. the resulting .po file must be translated - -4. finally, msgformat must be run to produce a .mo file: "binary message catalog" - - -How does it happen in practice? There is a Makefile in the "locale" -directory which will do almost everything (except translations) for you. i.e. -just type "make lang.po" to create or update the message catalog for 'lang'. -Then edit the resulting lang.po and make sure that there are no empty or fuzzy -translations left (empty translations are the ones with msgstr "", fuzzy -translations are those which have the word "fuzzy" in a comment just above -them). Then type "make lang.mo" which will create the binary message catalog. - -Under Windows (If you don't have Cygwin or MinGW), you should execute the -commands manually, please have a look at Makefile to see what must be done. - -For platform specific translations, .po files such as 'locale/msw/it.po' can be -used to provide translations that override the usual ones in 'locale/it.po'. -The generated .mo files are then installed under the names such as 'wxmsw.mo' -alongside the generic 'wxstd.mo'. - -A new platform specific translation should be added to a section such as this -in wx.bkl: - - - $(SRCDIR)/locale/msw - wxmsw - it - $(LOCALEDIR) - - -=== EOF === - -Author: VZ - -$Log$ -Revision 1.7 2005/08/12 15:34:01 MW -Typo - -Revision 1.6 2005/08/12 15:29:47 MW -Translate '&Help' to '&' for italian Windows only - -Revision 1.5 2004/10/22 19:12:59 KH -*** empty log message *** - -Revision 1.4 2004/05/04 08:26:58 JS -Name change replacements - -Revision 1.3 2003/11/18 16:37:11 DS -Updated translation technote to mention Makefile usage under Windows. - -Revision 1.2 2002/07/03 15:01:26 VZ -typos and other doc corrections from Olly Betts (patch 573738) - -Revision 1.1 2000/03/07 10:53:53 VZ -technote about translations added - +Please see index.txt diff --git a/docs/tech/tn0003.txt b/docs/tech/tn0003.txt index c1050e862c..03cb9b9653 100644 --- a/docs/tech/tn0003.txt +++ b/docs/tech/tn0003.txt @@ -1,315 +1 @@ - Adding wxWidgets class documentation - ==================================== - -This note is aimed at people wishing to add documentation for a -class to either the main wxWidgets manual, or to their own -manual. - -wxWidgets uses Doxygen to process header input files with embedded -documentation in the form of C++ comments and output in HTML, and XML -(Doxygen itself can also output Latex, manpages, RTF, PDF etc). -See http://www.doxygen.org for more info about Doxygen. - -If you want to add documentation of a new class/function to the -existing manual in docs/doxygen, you need to create a new .h file, -e.g. myclass.h, under the interface folder, which contains the public -interface of the new class/function in C++ syntax. -The documentation can then be added in form of Doxygen comments to -the header file. - -You may also want to write a separate topic file, -e.g. docs/doxygen/overviews/myclass.h, and add the entry to -docs/doxygen/mainpages/topics.h. - -If applicable, also add an entry to one of the docs/doxygen/mainpages/cat_*.h -files. - -You can generate a first raw version of myclass.h simply taking its -"real" header and removing all the private and protected sections and -in general removing everything the user "shouldn't know": i.e. all things -which are implementation details. - - -Running Doxygen -=============== - -First, make sure you have a recent version of Doxygen installed in your system -(you'll need Doxygen >= 1.5.7). - -On Unix: - - 1) run wxWidgets/docs/doxygen/regen.sh [format-to-generate] - -On Windows: - 1) cd wxWidgets/docs/doxygen - 2) run regen.bat [format-to-generate] - -If you don't specify which format to [re]generate, all output formats will -be enabled. Possible values for [format-to-generate] are: "html", "chm", "latex", -"xml" and "all". - -The output of Doxygen is all placed in the wxWidgets/docs/doxygen/out folder. - - -Important Dos and Don'ts -======================== - -DO: - -- Doxygen supports both commands in the form \command and @command; - all wxWidgets documentation uses the @command form. - Follow strictly this rule. - -- strive to use dedicated Doxygen commands for e.g. notes, lists, - sections, etc. The "Special commands" page: - http://www.stack.nl/~dimitri/doxygen/commands.html - is your friend! - It's also very important to make a consistent use of the ALIASES - defined by wxWidgets' Doxyfile. Open that file for more info. - -- when you write true, false and NULL with their C++ semantic meaning, - then use the @true, @false and @NULL commands. - -- separate different paragraphs with an empty comment line. - This is important otherwise Doxygen puts everything in the same - paragraph making the result less readable. - -- leave a blank comment line between a @section, @subsection, @page - and the next paragraph. - -- test your changes, both reading the generated HTML docs and by looking - at the "doxygen.log" file produced (which will warn you about any - eventual mistake found in the comments). - -- quote all the following characters prefixing them with a "@" char: - - @ $ \ & < > # % - - unless they appear inside a @code or @verbatim section - (you can also use HTML-style escaping, e.g. & rather than @ escaping) - -- when using a Doxygen alias like @itemdef{}, you need to escape the - comma characters which appear on the first argument, otherwise Doxygen - will interpret them as the marker of the end of the first argument and - the beginning of the second argument's text. - - E.g. if you want to define the item "wxEVT_MACRO(id, func)" you need to - write: - @itemdef{wxEVT_MACRO(id\, func), This is the description of the macro} - - Also note that you need to escape only the commas of the first argument's - text; second argument can have up to 10 commas unescaped (see the Doxyfile - for the trick used to implement this). - -- for linking use one of: - => the @ref command to refer to topic overviews; - => the () suffix to refer to function members of the same class you're - documenting or to refer to global functions or macros; - => the classname:: operator to refer to functions of classes different - from the one you're documenting; - => the :: prefix to refer to global variables (e.g. ::wxEmptyString). - Class names are auto-linked by Doxygen without the need of any explicit - command. - -DON'T: - -- use jargon, such as 'gonna', or omit the definite article. - The manual is intended to be a fluent, English document and - not a collection of rough notes. - -- use non-alphanumeric characters in link anchors. - -- use Doxygen @b @c @e commands when referring to more than a single word; - in that case you need to use the ..., ..., ... - HTML-style tags instead - -- use HTML style tags for creation of tables or lists. - Use wx aliases instead like @beginTable, @row2col, @row3col, @endTable and - @beginDefList, @itemdef, @endDefList, etc. - See the Doxyfile.inc for more info. - - -Documentation comment for a class -================================= - -Start off with: - -/** - @class wxMyClass - - ...here goes the description... - - @beginEventTable - @event{EVT_SOME_EVENT(id, func)}: - Description for EVT_SOME_EVENT. - @endEventTable - - @beginStyleTable - @style{wxSOME_STYLE}: - Description for wxSOME_STYLE. - ... - @endStyleTable - - @beginExtraStyleTable - @style{wxSOME_EXTRA_STYLE}: - Description for wxSOME_EXTRA_STYLE. - ... - @endExtraStyleTable - - @library{wxbase} - @category{cat_shortcut} - - @nativeimpl{wxgtk, wxmsw, ...} - @onlyfor{wxgtk, wxmsw, ...} - - @appearance{button.png} - - @stdobjects - ...here goes the list of predefined instances... - - @see ...here goes the see-also list... - you can make references to topic overviews or other - manual pages using the @ref command -*/ - -Note that everything *except* the @class, @library and @category -commands are optionals. - -Also note that if you use @section and @subsection in the class description -(at the beginning), you should use as the section's anchor name "xxxx_yyyy" -where "xxxx" is the class name without the initial "wx" in lowercase -and "yyyy" is a lowercase word which uniquely identifies that section. -E.g.: - -/** - @class wxMyClass - - This class does not exist really and is only used as an example - of best documentation practices. - - @section myclass_special Special functions of this class - - This section describes the functions whose usage is reserved for - wxWidgets internal mechanisms... etc etc... - - - @section myclass_custom Customizing wxMyClass - - What if you want to customize this powerful class? - First you should do this and that, etc etc... - - - @library{wxbase} - @category{misc} - - @see wxMyOtherClass -*/ - - - -Documentation comment for a function -==================================== - -Start off with: - -/** - ...here goes the description of the function.... - - @param param1 - ...here goes the description for the first parameter of this function - @param param2 - ...here goes the description for the second parameter of this function - ... - - @return - ...here goes the description of what the function returns... - - @note ...here go any eventual notes about this function... - - @remarks ...here go any eventual remarks about this function... - - @see ...here goes the see-also list... - */ - -Note that the @return, @note, @remarks, @see commands are optional. - -The @param command has an optional attribute specifying the direction of -the attribute. Possible values are "in" and "out". E.g. - -/** - * Copies bytes from a source memory area to a destination memory area, - * where both areas may not overlap. - * @param[out] dest The memory area to copy to. - * @param[in] src The memory area to copy from. - * @param[in] n The number of bytes to copy. - * @param[in,out] pmisc Used both as input and as output. - */ -void func(void *dest, const void *src, size_t n, void *pmisc); - - -Documentation comment for a topic overview -========================================== - -Topic overviews are stored inside the docs/doxygen/overviews folder -and are completely placed inside a single comment block in the form of: - -/*! - - @page overview_tname wxSomeStuff overview - - This page provides an overview of the wxSomeStuff and related classes. - .... - - @li @ref overview_tname_intro - @li @ref overview_tname_details - ... - -
- - - @section overview_tname_intro Introduction - - ...here goes the introduction to this topic... - - - @section overview_tname_details Details - - ...here go the details to this topic... - -*/ - -Note that there is a convention in the anchor link names. -Doxygen in fact requires that for each @page, @section, @subsection, etc tag, -there is a corresponding link anchor. - -The following conventions are used in wxWidgets doxygen comments: - -1) all "main" pages of the manual (those which are placed in - docs/doxygen/mainpages) have link anchors which begin with "page_" - -2) all topic overviews (those which are placed in docs/doxygen/overviews) have - link anchors which begin with "overview_" - -3) all @section, @subsection, @subsubsection tags should have as link anchor - name the name of the parent section plus a specific word separated with an - underscore; e.g.: - -/*! - - @page overview_tname wxSomeStuff overview - - @section overview_tname_intro Introduction - @subsection overview_tname_intro_firstpart First part - @subsection overview_tname_intro_secondpart Second part - @subsubsection overview_tname_intro_secondpart_sub Second part subsection - @subsection overview_tname_intro_thirdpart Third part - - @section overview_tname_details Details - ... - -*/ - - -=== EOF === - -Author: FM (along the lines of the previous technote about tex2rtf) +Please see index.txt diff --git a/docs/tech/tn0005.txt b/docs/tech/tn0005.txt deleted file mode 100644 index 8ffbb32e49..0000000000 --- a/docs/tech/tn0005.txt +++ /dev/null @@ -1,29 +0,0 @@ - Adding a wxWidgets contribution - =============================== - -Here are some different kinds of contribution: - -1. Bug fixes. You can send these to the wx-dev list. - -2. New classes. They should go somewhere in the wxWidgets - hierarchy if they are deemed to be 'core', otherwise they - could be placed in external repositories of wxWidgets - utilities, like wxCode (see http://wxcode.sf.net). - -3. A utility application, such as a new dialog editor or - file format conversion utility. If adding to the SVN - archive, you may put it under the utils hierarchy, - preferably with further src and docs directories. - -You may or may not wish to add your code to the main wxWidgets SVN -archive. Whether your code is appropriate for this archive -should first be ascertained by discussing it on wx-dev@wxwidgets.org. - -Also, in order to be included in wxWidgets, your code should -follow the wxWidgets coding conventions -(see http://www.wxwidgets.org/develop/standard.htm) and fit in the -wxWidgets src, include, docs directories hierarchy. - - -Author: Julian Smart - diff --git a/docs/tech/tn0009.htm b/docs/tech/tn0009.htm deleted file mode 100644 index 24aa30bb4d..0000000000 --- a/docs/tech/tn0009.htm +++ /dev/null @@ -1,59 +0,0 @@ - - - -Creating and converting icons - - - - - - - - - - - - -
- -Creating and converting icons - -
- -

- -Icons are bitmaps that may contain transparency information. Under X, icons are -usually created from XPM files, which may be loaded from a file or created from -data embedded in a C++ source file.

- -Under Windows, icon files (extension .ico) may contain multiple icons for different sizes and colour -depths, and can be loaded from a file or loaded from the Windows resources compiled -into the executable.

- -You can decide to use only XPMs on Windows and Unix, or you could use XPMs on Unix and -Windows icons under Windows -- the latter will require some #ifdefs in your code or use of the wxICON macro.

- -If you are using a compiler such as Borland C++ or Visual C++ you -can use the provided icon editor. However, if using Cygwin or Mingw32, there -is no icon editor so you must obtain one separately, such as IconEdit32.

- -To convert from XPM to BMP (which can be loaded or pasted into an icon editor to save as an ICO file), -you can use Vadim Zeitlin's xpm2bmp.exe utility. -To convert from BMP to XPM, you can use bmp2xpm.exe -which is actually the old wxWidgets 1.68 utility, xpmshow. You will have to edit the resulting -file since the full path is used as the variable name, plus you may wish to specify a transparent colour e.g.:

- -

-"  s None  c None",
-
- -This will indicate that the space character will be taken as the transparent colour throughout the image.

- - - - - - - diff --git a/docs/tech/tn0011.txt b/docs/tech/tn0011.txt index 4dd490dec8..03cb9b9653 100644 --- a/docs/tech/tn0011.txt +++ b/docs/tech/tn0011.txt @@ -1,51 +1 @@ - All about wxWidgets Version Numbers - =================================== - -1. Where to update the version numbers: - - There are several places in the wxWidgets source tree that - define the version number for the library. - - The script misc/scripts/inc_release can be used for incrementing the release - field of the version, i.e. changing 2.8.x to 2.8.x+1 but it does not take - care of version.bkl and can't be used for changing the other version - components, this needs to be done manually. It also doesn't update - version.bkl file which always needs to be updated manually, follow the - instructions there. - - Here is the list of files that need to be updated: - - build/bakefiles/version.bkl {C:R:A} [NOT UPDATED AUTOMATICALLY] - build/bakefiles/wxpresets/presets/wx.bkl [NOT UPDATED AUTOMATICALLY] - configure.in - build/osx/wxvers.xcconfig - docs/changes.txt - docs/readme.txt (date needs manual editing) [NOT UPDATED AUTOMATICALLY] - docs/doxygen/Doxyfile (PROJECT_NUMBER and DOCSET_FEEDNAME) - docs/doxygen/latexdocstart.inc - docs/doxygen/mainpages/manual.h (just date) [NOT UPDATED AUTOMATICALLY] - docs/msw/install.txt {major release only} - include/wx/version.h - include/wx/osx/config_xcode.h - samples/Info.plist - samples/docview/Info.plist - samples/minimal/Info_carbon.plist - samples/minimal/Info_cocoa.plist - samples/minimal/borland_ide.cpp {major release only} - - Do not forget to rebake everything after updating version.bkl! - -2. When to update the version numbers: - - Version should be updated immediately after releasing the previous version - so that the sources in the repository always correspond to the next release - and not the past one. - - See also tn0020.txt. - - - - -=== EOF === - - +Please see index.txt diff --git a/docs/tech/tn0012.txt b/docs/tech/tn0012.txt index 3115bbace1..03cb9b9653 100644 --- a/docs/tech/tn0012.txt +++ b/docs/tech/tn0012.txt @@ -1,122 +1 @@ - wxWidgets naming conventions - ============================ - -Being a cross platform development library, it is naturally desirable -(at least to me ;) for wxWidgets to be exploited in a fully cross -platform development environment -- a single invocation of make should -be sufficient to build target executables for a variety of host platforms -when desired. - -Since this is now in fact possible for at least the most commonly used -platforms, wxWidgets has been structured to allow multiple, simultaneous -installations of the library. Common files are shared, platform and port -specific files and libraries are arranged so as to be unambiguous when -installed together. - -To manage this sanely we need a sufficiently descriptive and logical -labelling convention for file and install path names -- this document (at -least at its time of writing) describes the system we have adopted. - -It is not fine grained enough to include every possible build configuration -for wxWidgets, but is encompassing enough to maintain a relatively complete -set of cross platform build tools on a single machine and to provide an -obvious slot for new ports to slip into. - - -For UNIX libraries, the canonical library name shall be of the form: - -libwx_$(toolkit)$(widgetset)$(debug)-$(version)-$(host).$(lib_extension) - -For MSW (native hosted only) libraries the library name should be of -the form: - -wx$(toolkit)$(widgetset)$(version)$(unicode)$(debug).$(lib_extension) - - -Where: - --------------------------------------------------------------------- - -$toolkit must currently be one of the following: - - msw - gtk - base - mac - motif - --------------------------------------------------------------------- - -$widgetset may be one of: - - univ - -or empty if the widget set is the same as the toolkit. - --------------------------------------------------------------------- - -$version is a string encoding the full version (major, minor, release) -for MSW, or just the major and minor number for UNIX. - -eg. for wxWidgets 2.3.2, $version = 232 for MSW or 2.3 for UNIX. - -The rationale for this is that under UNIX-like systems it is desirable -that differently 'minor numbered' releases can be installed together, -meaning your old 2.2 apps can continue to work even if you migrate -development to the next stable or unstable release (eg. 2.3, 2.4), -but binary compatibility is maintained between point releases (those -with the same major.minor number) - -A known break in binary compatibility should be addressed by updating -the library soname (see the notes in configure.in for details on this) - -I do not know why MSW should not also omit the release number from -$version. (maybe that will change by the time this document is ratified) - --------------------------------------------------------------------- - -$unicode and $debug are either empty or set to 'u' and 'd' -respectively when enabled. - --------------------------------------------------------------------- - -$host is empty for a 'native' library, (that is one where the host -system is the same as the build system) or set to the value returned -by the autoconf ${host_alias} variable in configure for libraries -that are cross compiled. - --------------------------------------------------------------------- - -$lib_extension is system specific and most usually set to .a for -a static library, .dll for a MSW shared library, or .so.$so_version -for a shared UNIX library. - -==================================================================== - - -The installed location of the library specific setup.h is also -determined by the values of these items. On UNIX systems they -will be found in: - -$(prefix)/lib/wx/include/$(toolkit)$(widgetset)$(debug)-$(version)-$(host)/wx/ - -which will be in the include search path returned by the relevant -wx-config for that library. (or presumably set in the relevant -make/project files for platforms that do not use wx-config) - -==================================================================== - - -The port specific wx-config file for each library shall be named: - -wx-$(toolkit)$(widgetset)$(debug)-$(version)-$(host)-config - -${prefix}/bin/wx-config shall exist as a link to (or copy of) one of -these port specific files (on platforms which support it) and as such -it defines the default build configuration for wxApps on the system. -It may be modified by the system user at any time. - - - - ---==O==--- - +Please see index.txt diff --git a/docs/tech/tn0015.txt b/docs/tech/tn0015.txt index 32f9d80e9c..03cb9b9653 100644 --- a/docs/tech/tn0015.txt +++ b/docs/tech/tn0015.txt @@ -1,120 +1 @@ - How to add new bitmaps to wxWidgets UI elements - =============================================== - -0. Introduction ---------------- - -Since the introduction of wxArtProvider class, it is no longer desired to -hardcode art resources (e.g. icons and toolbar or button bitmaps) into the -code. This was previously done either by including the bitmap in win32 -resource file (include/wx/msw/wx.rc) or by including XPM files in the code. - -wxArtProvider should be used instead, to allow users to customize the look of -their wxWidgets app. This technote is a detailed description of steps needed -when adding new bitmap/icon. - -1. Adding new resource ----------------------- - -(Please see wxArtProvider reference documentation for explanation of "art ID" - and "art client" terms.) - -First of all, you have to add new wxArtID constant to include/wx/artprov.h. -Look for "Art IDs" and add new definition to the list, e.g. - #define wxART_MY_BITMAP wxART_MAKE_ART_ID(wxART_MY_BITMAP) - -Add it to interface/wx/artprov.h, too. - -It may happen that the intended use of the new resource doesn't fit into any -of defined client categories (search for "Art clients" in the header). In case -the new resource is part of a larger category, you need to define a new -client. Just add it to the list of existing clients (and don't forget to -update artprov.tex): - #define wxART_MY_CLIENT wxART_MAKE_CLIENT_ID(wxART_MY_CLIENT) - -Alternatively, you may use wxART_OTHER when accessing the resource if the -bitmap is standalone. - -Once the header is updated, it's time to add XPM file with the bitmap to -$(wx)/art. Add it to $(wx)/art if it is platform-independent or to -$(wx)/art/$(toolkit) if it is something specific to one of the toolkits. Note -that "specific to one of the toolkits" doesn't mean that the bitmap is *used* -by only one toolkit, but that it doesn't make sense for any of the others! For -example, a GTK wxART_WARNING icon ($(wx)/art/gtk/warning.xpm) is specific to -wxGTK, but new_dir.xpm makes sense even under wxMSW even though it is -currently only used by the generic file dialog. Remember that wxArtProvider -can be used by users, not only the library. - -Finally, wxDefaultArtProvider in $(wx)/src/common/artstd.cpp must be updated. -This consists of two steps: - - a) add #include line for your XPM file, e.g. #include "../../art/my_bmp.xpm" - b) add ART(...) line to wxDefaultArtProvider::CreateBitmap(). The first - argument is wxArtID, the other is XPM file name (w/o extension), e.g. - ART(wxART_MY_BITMAP, my_bmp) - -That's all. The bitmap is now available to wxArtProvider users. - -Note: there's no difference between icons and bitmaps, always treat them as -bitmaps inside wx(Default)ArtProvider. - -1b. Adding Tango version of the resource. ------------------------------------------ - -While all the bitmaps are provided in XPM format so that they are available in -all builds of wxWidgets, we also provide most of them in PNG format with full -transparency support that is not available in XPM. Another advantage of the PNG -versions is that the icons used are those of the Tango project and so have the -consistent look, unlike the XPM ones. - -So if you an icon exists in http://tango.freedesktop.org/Tango_Icon_Gallery you -should add it too. For this you need to: - -1. Convert the PNG to a C array of bytes suitable for inclusion in the code. - This is done using misc/scripts/png2c.py script, e.g. if the variable "f" - contains the name of the icon you want to add and you have installed Tango - icons in a standard location under a Linux system: - - ./misc/scripts/png2c.py -s /usr/share/icons/Tango/{16x16,24x24}/*/$f.png > - art/tango/${f//-/_}.h - - Of course, the same command may be ran with different paths under Windows. - Just remember to add both 16 and 24 pixel versions of the bitmap to the - header and use the "-s" option to embed the image size in its array name. - -2. Add #include for the newly created file to src/common/arttango.cpp. - -3. Add an entry to s_allBitmaps array in the same file. - - -2. Accessing the resource -------------------------- - -The file that will use the bitmap needs to include "wx/artprov.h". The code to -access the bitmap (or icon) is trivial: - - wxBitmap bmp = wxArtProvider::GetBitmap(wxART_MY_BITMAP, wxART_MY_CLIENT); - // this would be "wxBitmap bmp(my_bmp_xpm);" before - wxIcon icon = wxArtProvider::GetIcon(wxART_MY_ICON, wxART_MY_CLIENT); - -Substitute wxART_MY_CLIENT in the example with a suitable client ID. If the -client is wxART_OTHER you may write only - - wxArtProvider::GetBitmap(wxART_MY_BITMAP). - -3. Providing a demo -------------------- - -It is highly desirable to let the users know what stock bitmaps are available -in wxWidgets. The "artprov" sample serves this purpose: it contains a browser -dialog that displays all available art resources. - -It has to be updated to accommodate for new bitmaps. Fortunately, this is -trivial: open $(wx)/samples/artprov/artbrows.cpp in text editor and -ART_ICON(wxART_MY_BITMAP) line to the FillBitmaps() function. - -Similarly, if you add a new client, please update FillClients() by adding new -client to the end of the list. - -=== EOF === - +Please see index.txt diff --git a/docs/tech/tn0016.txt b/docs/tech/tn0016.txt index 6b142b0603..03cb9b9653 100644 --- a/docs/tech/tn0016.txt +++ b/docs/tech/tn0016.txt @@ -1,227 +1 @@ - How to add new files and libraries to wxWidgets build system - ============================================================ - - -1. Regenerating makefiles -------------------------- - -wxWidgets now uses Bakefile (http://bakefile.sourceforge.net) to generate -native makefiles. You must have bakefile installed if you want to regenerate -the makefiles. Bakefile currently runs on Unix and Windows systems. You will -need Python >= 2.2 installed on Unix and either use Bakefile installer or have -Python on Windows. - -Once you have installed Bakefile, you can easily regenerate the makefiles using -the bakefile_gen tool. Run it from $(wx)/build/bakefiles directory and it will -regenerate all outdated makefiles. See $(wx)/build/bakefiles/README for more -details. - -Note that it generates makefiles for samples, too. - -IMPORTANT NOTE: Don't forget to run autoconf in wxWidgets root directory - (after running Bakefile) if you changed any conditional - variable or target condition in .bkl files! You will know that - this happened if $(wx)/autoconf_inc.m4 content changed. - -You can use Bakefile to generate makefiles or projects customized to your -needs, too. See Bakefiles.bkgen for details on bakefile commands used to -generate makefiles. For example, you can use this command to generate -VC++ project files without wxUniversal configurations: - bakefile -v -fmsvc6prj -o../wxmy.dsw -DRUNTIME_LIBS=dynamic - -DDEBUG_INFO=default -DDEBUG_FLAG=default - -DOFFICIAL_BUILD=0 -DUSE_HTML=1 -DUSE_OPENGL=1 - -DMONOLITHIC=0 -DUSE_GUI=1 -DWXUNIV=0 wx.bkl -Or monolithic instead of multilib (the default): - bakefile -v -fmsvc6prj -o../wxmono.dsw -DRUNTIME_LIBS=dynamic - -DDEBUG_INFO=default -DDEBUG_FLAG=default - -DOFFICIAL_BUILD=0 -DUSE_HTML=1 -DUSE_OPENGL=1 - -DMONOLITHIC=1 -DUSE_GUI=1 wx.bkl -Or monolithic wxBase: - bakefile -v -fmsvc6prj -o../wxBase.dsw -DRUNTIME_LIBS=dynamic - -DDEBUG_INFO=default -DDEBUG_FLAG=default - -DOFFICIAL_BUILD=0 -DUSE_HTML=0 -DUSE_OPENGL=0 - -DMONOLITHIC=1 -DUSE_GUI=0 wx.bkl -It is, however, recommended to modify Bakefiles.bkgen (or -Bakefiles.local.bkgen) by means of and directives -and use bakefile_gen instead of running bakefile directly. - - -2. Bakefile files organization ------------------------------- - -Makefile are generated from .bkl files ("bakefiles") from two places: - - $(wx)/build/bakefiles directory - - samples directories -$(wx)/build/bakefiles contains bakefiles for main library and support files -that simplify writing bakefiles for samples. - -Support files are: - wxwin.py - helper functions - common.bkl - common_samples.bkl - config.bkl - user-configurable build options - make_dist.mk - implementation of "make dist" on Unix - -Files used to build the library are: - wx.bkl - main file - files.bkl - lists of source files - monolithic.bkl - targets for wxWin built as single big library - multilib.bkl - targets for multilib build - opengl.bkl - GL library with wxGLCanvas (this one is not - included in monolithic library for historical - reasons, so "monolithic" really means "two libs") - {expat,jpeg,png,tiff, - regex,zlib,odbc}.bkl - 3rd party libraries makefiles - - -3. Adding files to existing library ------------------------------------ - -UPDATE: files.bkl is now itself partially generated from the master file - build/files. If the variable which you need to modify, according to the - instructions below, is already defined in build/files, update it there - and run build/upmake to update files.bkl. - - -All files used by main libraries are listed in files.bkl. The file is -organized into variables for toolkits, platforms and libraries. The variables -come in pairs: there's always FOO_SRC for source files and FOO_HDR for header -files. Platform or toolkit specific files are grouped together in variable -with platform or toolkit name in them, e.g. BASE_WIN32_SRC, BASE_UNIX_SRC, -GTK_SRC, MOTIF_SRC. - -Note: A side effect of this toolkit-centric organization is that one file may - be present several times in files.bkl in different contexts. - -When you are adding a file, you must put it into appropriate variable. This is -easy if you are adding the file to library that is always built from same -sources on all platforms (e.g. wxXml or wxXML) -- simply add the file to e.g. -HTML_SRC or HTML_HDR. - -If the file is used only on one platform and is part of wxBase, add it to -BASE_{platform}_SRC/HDR. If it is used on all platforms, add it to BASE_CMN. -If it is built on more than one platform but not on all of them, add the file -to *all platforms that use it*! - -If a file is not wxBase file, but GUI file, then the variables are named after -toolkits/ports, not platforms. Same rules as for wxBase files apply -(substitute "platform" with "toolkit"). Make sure you correctly choose between -{port}_LOWLEVEL_SRC and {port}_SRC -- the former is for files used by -wxUniversal, e.g. GDI classes. Files shared by all X Window System ports -should be put into XWIN_LOWLEVEL_SRC. - - -4. Adding sample ----------------- - -Copy the bakefile from another sample, change the ID and files accordingly. -If the sample uses some data files, make sure to have node -in the sample's bakefile (see e.g. samples/image/image.bkl for an example). -Make sure to add statements for all libraries from multilib build -that are required by the sample. - -The Windows resource specification should use the central .rc file: - - ../sample.rc - -Run bakefile_gen in $(wx)/build/bakefiles to regenerate the bakefiles. - -Finally commit $(wx)/build/bakefiles/make_dist.mk and all the other modified files. - -Currently we commit the generated makefiles except .dms, .vcp. - - -5. Adding new core library --------------------------- - -When adding new library to the core set of libraries, the files must be -added to both a newly added library in multilib build and into the single -library built in monolithic mode. We will assume that the new library is -called wxFoo. - -a) Add files to files.bkl: - * If wxFoo builds from same files on all platforms (e.g. wxNet), - add FOO_SRC and FOO_HDR variables with lists of sources and headers. - * If wxFoo have no files in common (e.g. wxGL), add FOO_SRC and FOO_HDR - with toolkit or platform conditions. Have a look at OPENGL_SRC for an - example. - * Otherwise add FOO_CMN_SRC and FOO_CMN_HDR for common files and - FOO_{platform}_{SRC,HDR} or FOO_{toolkit}_{SRC,HDR} as appropriate. Add - FOO_PLATFORM_{SRC,HDR} into "Define sources for specific libraries" - section that is conditionally set to one of FOO_xxx_{SRC,HDR} based on - target platform/toolkit (see NET_PLATFORM_SRC definition for an example). - Finally, define FOO_SRC and FOO_HDR to contain both - FOO_PLATFORM_{SRC,HDR} and FOO_{SRC,HDR} (see NET_SRC definition for an - example). - * Add FOO_HDR to ALL_GUI_HEADERS or ALL_BASE_HEADERS. - * If wxFoo is wxBase library (doesn't use GUI), add FOO_SRC to - ALL_BASE_SOURCES. - - (You can apply different approaches to HDR and SRC variables, if e.g. - headers are all common but sources are not.) - - Note that the conditions can only test for equality, due to limitations of - native make tools. - -b) Modify bakefile system in build/bakefiles/ to recognize wxFoo: - * Add 'foo' to MAIN_LIBS and LIBS_NOGUI or LIBS_GUI (depending on whether - the library depends on wxCore or not) to wxwin.py file. - * Add extra libraries needed by wxFoo (if any) to EXTRALIBS in wxwin.py - * Add WXLIB_FOO definition to common.bkl (into the "Names of component - libraries" section). It looks like this: - - $(mk.evalExpr(wxwin.mkLibName('foo'))) - - -c) Modify monolithic.bkl to add files to monolithic build: it's enough to add - FOO_SRC to MONOLIB_GUI_SRC or MONOLIB_SRC, depending on whether wxFoo uses - GUI or not. - -d) Modify multilib.bkl to add files to multilib build: add foolib and foodll - targets. Don't use wxBase targets as the template, use e.g. wxXML or wxHTML. - Make sure WXMAKINGDLL_FOO is defined in foodll. - -e) Regenerate all makefiles (don't forget to run autoconf) - -f) Update configure.in and wx-config.in to contain information about - the library and needed linker flags: - * Add "foo" to BUILT_WX_LIBS in configure.in. - * If appropriate, but it rarely is, so normally this should _not_ be done, - add "foo" to either STD_BASE_LIBS or STD_GUI_LIBS in configure.in. - * If wxFoo links against additional libraries, add necessary linker - flags and libraries to ldflags_foo and ldlibs_foo variables in - wx-config.in (both are optional). - -g) Update dlimpexp.h to define WXMAKINGDLL_FOO if WXMAKINGDLL is defined (add - #define WXMAKINGDLL_FOO inside first "#ifdef WXMAKINGDLL" block in - dlimpexp.h) and to define WXDLLIMPEXP_FOO and WXDLLIMPEXP_DATA_FOO. You - can copy e.g. WXDLLIMPEXP_NET definition, it is something like this: - #ifdef WXMAKINGDLL_NET - #define WXDLLIMPEXP_NET WXEXPORT - #define WXDLLIMPEXP_DATA_NET(type) WXEXPORT type - #elif defined(WXUSINGDLL) - #define WXDLLIMPEXP_NET WXIMPORT - #define WXDLLIMPEXP_DATA_NET(type) WXIMPORT type - #else // not making nor using DLL - #define WXDLLIMPEXP_NET - #define WXDLLIMPEXP_DATA_NET(type) type - #endif - Don't forget to add WXDLLIMPEXP_FWD_FOO definitions too. - Use WXDLLIMPEXP_FOO when declaring wxFoo classes and functions. - -h) Add this code to one of wxFoo's files (the more often used, the better): - // DLL options compatibility check: - #include "wx/app.h" - WX_CHECK_BUILD_OPTIONS("wxFoo") - -i) Add information about wxFoo to the manual ("Libraries list" section - in libs.tex) and update docs/latex/wx/libs.dia (you need Dia for this) - to show the dependencies of the new library. - -j) Also please add 4 #pragma comment(lib, "foo") (for Unicode/ANSI - Release/Debug combinations) to the file include/msvc/wx/setup.h and - add a check for WXMAKINGDLL_FOO to the test whether we're building a DLL at - the end of include/wx/msw/chkconf.h. - -=== EOF === - +Please see index.txt diff --git a/docs/tech/tn0017.txt b/docs/tech/tn0017.txt index 94012357f9..03cb9b9653 100644 --- a/docs/tech/tn0017.txt +++ b/docs/tech/tn0017.txt @@ -1,144 +1 @@ - How to write unit tests for wxWidgets - ===================================== - -Unit tests for wxWidgets are written using small cppunit framework. To compile -(but not to run) them you need to have it installed. Hence the first part of -this note explains how to do it while the second one explains how to write the -test. - -I. CppUnit Installation ------------------------ - -1. Get it from http://www.sourceforge.net/projects/cppunit - (latest version as of the time of this writing is 1.10.2) - -2. Build the library: - a) Under Windows using VC++: - - build everything in CppUnitLibraries.dsw work space - - add include and lib subdirectories of the directory - where you installed cppunit to the compiler search path - using "Tools|Options" menu in VC IDE - - b) Under Unix: run configure && make && make install as usual - - -II. Writing tests with CppUnit ------------------------------- - -1. Create a new directory tests/foo - -2. Write a cpp file for the test copying, if you want, - from one of the existing tests. The things to look for: - a) #include "wx/cppunit.h" instead of directly including CppUnit headers - b) don't put too many things in one test case nor in one method of a test - case as it makes understanding what exactly failed harder later - c) 'register' your tests as follows so that the test program will find and - execute them: - - // register in the unnamed registry so that these tests are run by default - CPPUNIT_TEST_SUITE_REGISTRATION(MBConvTestCase); - - // also include in its own registry so that these tests can be run alone - CPPUNIT_TEST_SUITE_NAMED_REGISTRATION(MBConvTestCase, "MBConvTestCase"); - - Read CppUnit documentation for more. - d) wxUIActionSimulator can be used when user input is required, for example - clicking buttons or typing text. A simple example of this can be found - in controls/buttontest.cpp. After simulating some user input always - wxYield to allow event processing. When writing a test using - wxUIActionSimulator always add the test using WXUISIM_TEST rather than - CPPUNIT_TEST as then it won't run on unsupported platforms. The test itself - must also be wrapped in a #if wxUSE_UIACTIONSIMULATOR block. - e) There are a number of classes that are available to help with testing GUI - elements. Firstly throughout the test run there is a frame of type - wxTestableFrame that you can access through wxTheApp->GetTopWindow(). This - class adds two new functions, GetEventCount, which takes an optional - wxEventType. It then returns the number of events of that type that it has - received since the last call. Passing nothing returns the total number of - event received since the last call. Also there is OnEvent, which counts the - events based on type that are passed to it. To make it easy to count events - there is also a new class called EventCounter which takes a window and event - type and connects the window to the top level wxTestableFrame with the specific - event type. It disconnects again once it is out of scope. It simply reduces - the amount of typing required to count events. - -3. add a '' tag for your source file to tests/test.bkl. Make sure it's - in the correct section: the one starting ' or be -included directly. So instead of #include <...> use "wx/msw/wrapwin.h" or -"wx/msw/wrapcctl.h". - -For convenience it is also possible to replace #include and - with #include "wx/msw/wrapcdlg.h" and wrapshl.h but this is less -vital. - -Also notice that many convenient (albeit undocumented) functions and classes -are declared in "wx/msw/private.h", please do become familiar with this file -contents and use the utility classes and functions from it instead of -duplicating their functionality (which can often be done only in exception -unsafe way). - - -2. Windows features checks --------------------------- - -All checks of features not present in all Windows versions must be done both at -compile-time (because, even though we use maximal value for WINVER in our code, -some compilers come with headers too old to declare them) and at run-time -(because wxMSW applications should run everywhere). - -The functions wxGetWinVersion() (from wx/msw/private.h) and wxApp:: -GetComCtl32Version() should be used to check Windows and comctl32.dll versions -respectively. - -Any functions which may not be present in kernel32.dll/user32.dll/... in all -Windows versions should be resolved dynamically, i.e. using wxDynamicLibrary as -otherwise any wx application -- even not needing them at all -- would refuse to -start up on Windows versions not implementing the feature in question. As an -example, look at AlphaBlt()-related code in src/msw/dc.cpp. - - -=== EOF === - -Author: VZ +Please see index.txt diff --git a/docs/tech/tn0020.txt b/docs/tech/tn0020.txt index 69f610d2e7..03cb9b9653 100644 --- a/docs/tech/tn0020.txt +++ b/docs/tech/tn0020.txt @@ -1,287 +1 @@ - Binary Compatibility and wxWidgets - ================================== -0. Purpose ----------- - -This is a broad technote covering all aspects of binary compatibility with -wxWidgets. - -1. Releases ------------ - -General overview of releases can be found in tn0012.txt, but for -completeness the wxWidgets release version number is as follows: - -2.6.2 - -Where - - 2 6 2 -Major Minor Release - -(I.E. Major.Minor.Release). - -All versions with EVEN minor version component (e.g. 2.4.x, 2.6.x etc.) -are expected to be binary compatible (ODD minors are development versions -and the compatibility constraints don't apply to them). Note that by -preserving binary compatibility we mean BACKWARDS compatibility only, -meaning that applications built with old wxWidgets headers should continue -to work with new wxWidgets (shared/dynamic) libraries without the need to -rebuild. There is no requirement to preserve compatibility in the other -direction (i.e. make new headers compatible with old libraries) as this -would preclude any additions whatsoever to the stable branch. But see -also section (4). - - -2. What kind of changes are NOT binary compatible -------------------------------------------------- - -If its still up, the KDE guide is a good reference: -http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C++ - -The changes that are NOT binary compatible: -- Adding a virtual function -- Changing the name of a any function or variable -- Changing the signature of a virtual function (adding a parameter, -even a default one) -- Changing the order of the virtual functions in a class -["switching" them, etc.] -- Changing access privileges of a function: some compilers (among which MSVC) - use the function access specifier in its mangled name. Moreover, while - changing a private function to public should be compatible (as the old - symbol can't be referenced from outside the library anyhow), changing a - virtual private function to public is NOT compatible because the old symbol - is referenced by the virtual tables in the executable code and so an old - program compiled with MSVC wouldn't start up with a new DLL even if it - doesn't use the affected symbol at all! -- Adding a member variable -- Changing the order of non-static member variables - - -3. Changes which are compatible -------------------------------- - -- Adding a new class -- Adding a new non-virtual method to an existing class -- Adding a new constructor to an existing class -- Overriding the implementation of an existing virtual function -[this is considered to be backwards binary compatible until we find a - counter example; currently it's known to work with Apple gcc at least] -- Anything which doesn't result in ABI change at all, e.g. adding new - macros, constants and, of course, private changes in the implementation - - -4. wxABI_VERSION and "forward" binary compatibility --------------------------------------------------- - -As mentioned we do not support "forward" binary compatibility, that is the -ability to run applications compiled with new wxWidgets headers on systems -with old wxWidgets libraries. - -However, for the developers who want to ensure that their application works -with some fixed old wxWidgets version and doesn't (inadvertently) require -features added in later releases, we provide the macro wxABI_VERSION which -can be defined to restrict the API exported by wxWidgets headers to that of -a fixed old release. - -For this to work, all new symbols added to binary compatible releases must -be #if'ed with wxABI_VERSION. - -The layout of wxABI_VERSION is as follows: - -20602 - -where - - 2 06 02 -Major Minor Release - -I.E. it corresponds to the wxWidgets release in (1). - -An example of using wxABI_VERSION is as follows for symbols -only in a 2.6.2 release: - -#if wxABI_VERSION >= 20602 /* 2.6.2+ only */ -bool Load(const wxURI& location, const wxURI& proxy); - -wxFileOffset GetDownloadProgress(); -wxFileOffset GetDownloadTotal(); - -bool ShowPlayerControls( - wxMediaCtrlPlayerControls flags = - wxMEDIACTRLPLAYERCONTROLS_DEFAULT); - -//helpers for the wxPython people -bool LoadURI(const wxString& fileName) -{ return Load(wxURI(fileName)); } -bool LoadURIWithProxy(const wxString& fileName, const wxString& proxy) -{ return Load(wxURI(fileName), wxURI(proxy)); } -#endif - - -5. Workarounds for adding virtual functions -------------------------------------------- - -Originally the idea for adding virtual functions to binary compatible -releases was to pad out some empty "reserved" functions and then -rename those later when someone needed to add a virtual function. - -However, after there was some actual testing of the idea a lot of -controversy erupted. Eventually we decided against the idea, and -instead devised a new method for doing so called wxShadowObject. - -wxShadowObject is a class derived from wxObject that provides a means -of adding functions and/or member variables to a class internally -to wxWidgets. It does so by storing these in a hash map inside of -it, looking it up when the function etc. is called. wxShadowObject -is generally stored inside a reserved member variable. - -wxShadowObject resides in include/wx/clntdata.h. - -To use wxShadowObject, you first call AddMethod or AddField with -the first parameter being the name of the field and/or method -you want, and the second parameter being the value of the -field and/or method. - -In the case of fields this is a void*, and in the case of method -is a wxShadowObjectMethod which is a typedef: -typedef int (*wxShadowObjectMethod)(void*, void*); - -After you add a field, you can set it via SetField with the same -parameters as AddField, the second parameter being the value to set -the field to. You can get the field after you call AddField -via GetField, with the parameters as the other two field functions, -only in the case the second parameter is the fallback -value for the field in the case of it not being found in the -hash map. - -You can call a method after you add it via InvokeMethod, which -returns a bool indicating whether or not the method was found -in the hash map, and has 4 parameters. The first parameter is -the name of the method you wish to call, the second is the first -parameter passed to the wxShadowObjectMethod, the third is the -second parameter passed to that wxShadowObjectMethod, and the -fourth is the return value of the wxShadowObjectMethod. - -6. version-script.in --------------------- - -For ld/libtool we use sun-style version scripts. Basically -anything which fits the conditions of being #if'ed via wxABI_VERSION -needs to go here also. - -See 'info ld scripts version' on a GNU system, it's online here: -http://www.gnu.org/software/binutils/manual/ld-2.9.1/html_node/ld_25.html - -Or see chapter 5 of the 'Linker and Libraries Guide' for Solaris, available -online here: -http://docsun.cites.uiuc.edu/sun_docs/C/solaris_9/SUNWdev/LLM/p1.html - -The file has the layout as follows: - -@WX_VERSION_TAG@.X - -Where X is the current Release as mentioned earlier, i.e. 2. This -is following by an opening bracket "{", followed by "global:", -followed by patterns matching added symbols, then followed by "}", and then -the file is either followed by earlier Releases or ended by -a @WX_VERSION_TAG@ block without the period or Release. - -The patterns used to specify added symbols are globbing patters and can -contain wildcards such as '*'. - -For example for a new class member such as: - wxFont wxGenericListCtrl::GetItemFont( long item ) const; - -the mangled symbol might be: - _ZNK17wxGenericListCtrl11GetItemFontEl - -so a line like this could be added to version-script.in: - *wxGenericListCtrl*GetItemFont*; - -Allow for the fact that the name mangling is going to vary from compiler to -complier. - -When adding a class you can match all the symbols it adds with a single -pattern, so long as that pattern is not likely to also match other symbols. -For example for wxLogBuffer a line like this: - *wxLogBuffer*; - - -7. Checking the version information in libraries and programs -------------------------------------------------------------- - -On Sun there is a tool for this, see pvs(1). On GNU you can use objdump, below -are some examples. - -To see what versions of each library a program (or library) depends on: - -$ objdump -p widgets | sed -ne '/Version References/,/^$/p' -Version References: - required from libgcc_s.so.1: - 0x0b792650 0x00 10 GCC_3.0 - required from libwx_based-2.6.so.0: - 0x0cca2546 0x00 07 WXD_2.6 - required from libstdc++.so.6: - 0x056bafd3 0x00 09 CXXABI_1.3 - 0x08922974 0x00 06 GLIBCXX_3.4 - required from libwx_gtk2d_core-2.6.so.0: - 0x0a2545d2 0x00 08 WXD_2.6.2 - 0x0cca2546 0x00 05 WXD_2.6 - required from libc.so.6: - 0x09691a75 0x00 04 GLIBC_2.2.5 - -To see what WXD_2.6.2 symbols a program uses: - -$ objdump -T widgets | grep 'WXD_2\.6\.2' -0000000000000000 g DO *ABS* 0000000000000000 WXD_2.6.2 WXD_2.6.2 -00000000004126d8 DF *UND* 0000000000000177 WXD_2.6.2 _ZN19wxTopLevelWindowGTK20RequestUserAttentionEi - -To see what WXD_2.6.2 symbols a library defines: - -$ objdump -T libwx_based-2.6.so | grep 'WXD_2\.6\.2' | grep -v 'UND\|ABS' -0000000000259a10 w DO .data 0000000000000018 WXD_2.6.2 _ZTI19wxMessageOutputBest -00000000002599e0 w DO .data 0000000000000028 WXD_2.6.2 _ZTV19wxMessageOutputBest -000000000010a98e w DF .text 000000000000003e WXD_2.6.2 _ZN19wxMessageOutputBestD0Ev -0000000000114efb w DO .rodata 000000000000000e WXD_2.6.2 _ZTS11wxLogBuffer -0000000000255590 w DO .data 0000000000000018 WXD_2.6.2 _ZTI11wxLogBuffer -000000000011b550 w DO .rodata 0000000000000016 WXD_2.6.2 _ZTS19wxMessageOutputBest -00000000000bfcc8 g DF .text 00000000000000dd WXD_2.6.2 _ZN11wxLogBuffer5DoLogEmPKcl -000000000010a3a6 g DF .text 0000000000000153 WXD_2.6.2 _ZN19wxMessageOutputBest6PrintfEPKcz -00000000000c0b22 w DF .text 000000000000004b WXD_2.6.2 _ZN11wxLogBufferD0Ev -00000000000bfc3e g DF .text 0000000000000089 WXD_2.6.2 _ZN11wxLogBuffer5FlushEv -00000000000c0ad6 w DF .text 000000000000004b WXD_2.6.2 _ZN11wxLogBufferD1Ev -00000000000b1130 w DF .text 0000000000000036 WXD_2.6.2 _ZN11wxLogBufferC1Ev -00000000000c095c w DF .text 0000000000000029 WXD_2.6.2 _ZN19wxMessageOutputBestC1Ev -00000000000c08e8 w DF .text 000000000000003e WXD_2.6.2 _ZN19wxMessageOutputBestD1Ev -00000000002554c0 w DO .data 0000000000000038 WXD_2.6.2 _ZTV11wxLogBuffer -00000000000bfda6 g DF .text 0000000000000036 WXD_2.6.2 _ZN11wxLogBuffer11DoLogStringEPKcl -00000000000abe10 g DF .text 0000000000000088 WXD_2.6.2 _ZN14wxZipFSHandler7CleanupEv - - -8. Testing binary compatibility between releases ------------------------------------------------- - -An easy way of testing binary compatibility is just to build wxWidgets -in dll/dynamic library mode and then switch out the current library -in question with an earlier stable version of the library, then running -the application in question again. If it runs OK then there is usually -binary compatibility between those releases. - -You can also break into your debugger or whatever program you want -to use and check the memory layout of the class. If it is the same -then it is binary compatible. -(In GDB the command x/d will show addresses as pointers to functions if -possible so you can see if the order of the functions in vtbl doesn't change.) - -Another way to check for binary compatibility is to build wxWidgets in shared mode -and use the 'abicheck.sh --generate' script before doing your changes to generate -the current ABI (if the 'expected_abi' file is not already in the repo). -Then rebuild wxWidgets with your changes and use 'abicheck.sh' to compare the -resulting ABI with the expected one. -Note that the abicheck.sh script is in the "lib" folder. - - -=== EOF === - -Author: RN +Please see index.txt diff --git a/docs/tech/tn0021.txt b/docs/tech/tn0021.txt index 1bd5cafb5e..03cb9b9653 100644 --- a/docs/tech/tn0021.txt +++ b/docs/tech/tn0021.txt @@ -1,83 +1 @@ - How to add a new wxUSE_XXX preprocessor constant - ================================================ - -0. Purpose ----------- - -Detailed description of what needs to be done when you want to add a new -wxUSE_XXX compilation flag. The text below assumes you need new wxUSE_FOO. - - -1. Overview ------------ - -wxWidgets uses wxUSE_XXX macros for conditionally compiling in (or not) -optional components. In general, whenever a new non critical (i.e. not -absolutely required by important parts of the library) class Foo is added it -should use its own wxUSE_FOO compilation flag. - -wxUSE_FOO must be always defined and have value of 0 or 1. Be careful with -testing for it in wx/foo.h: don't do it at the very beginning of the file -because then wxUSE_FOO would be not defined at all if the user directly -includes wx/foo.h, include "wx/defs.h" before testing for wxUSE_FOO. - - -2. Files to update ------------------- - -The following files need to be modified when adding a new wxUSE_FOO: - -a) include/wx/setup_inc.h - - This file contains all common wxUSE_XXXs, and is used to update wxMSW, wxMac - setup.h and Unix setup.h.in using build/update-setup-h. Please try to add - the new define in a logical place (i.e. near any related ones) and write a - detailed comment explaining what does it do and why would you want to turn - it on/off. Choose the appropriate default value: this should be usually 1 - but can be 0 if there are some problems preventing the use of Foo by default - (e.g. it requires installation of some non standard 3rd party libraries). - After changing this file, run the update-setup-h script (this is probably - better done on a Unix machine although it should work under Cygwin too). - -a') include/wx/msw/setup_inc.h for MSW-specific options - - This file contains MSW-specific options, so if the new option is only used - under MSW, add it here instead of include/wx/setup_inc.h. The rest of the - instructions is the same as above. - -b) include/wx/chkconf.h - - Add the check for wxUSE_FOO definedness in the corresponding (base or GUI) - section. Please keep the alphabetic order. - - If there are any dependencies, i.e. wxUSE_FOO requires wxUSE_BAR and - wxUSE_BAZ, check for thme here too. - -b') include/wx/msw/chkconf.h for MSW-specific options - - These options won't be defined for the other ports, so shouldn't be added to - the common include/wx/chkconf.h but to this file instead. - -c) configure.in - - Here you need to add DEFAULT_wxUSE_FOO define. It should be added in the - block beginning after WX_ARG_CACHE_INIT line and should default to "no" for - "if DEBUG_CONFIGURE = 1" branch (this is used for absolutely minimal builds) - and the same as default value in setup_inc.h in the "else" branch. - - You also need to add a WX_ARG_ENABLE (or, if new functionality can be - reasonably described as support for a 3rd party library, WX_ARG_WITH) - line togetherw with all the existing WX_ARG_ENABLEs. - - If you have a sample/foo which should be only built when wxUSE_FOO==1, - then only add it to the SAMPLES_SUBDIRS if wxUSE_FOO=yes in configure. - -d) docs/doxygen/mainpages/const_wxusedef.h - - Add a brief description of the new constant. - - -=== EOF === - -Author: VZ - +Please see index.txt diff --git a/docs/tech/tn0022.txt b/docs/tech/tn0022.txt index 7cccd99349..03cb9b9653 100644 --- a/docs/tech/tn0022.txt +++ b/docs/tech/tn0022.txt @@ -1,180 +1 @@ - Making a new wxWidgets release - ============================== - -Before making the release -------------------------- - -Change the version in include/wx/version.h. - -Update docs/readme.txt. Please review its contents in addition to just -changing the version number. - -Put a date on the release line in docs/changes.txt. - -Update the date in the manual (docs/doxygen/mainpages/manual.h). - -Update the release announcement post in docs/publicity/announce.txt. - - -Creating release files ----------------------- - -The currently used release scripts need to be used from git-svn checkout and -rely on Git to avoid problems with using non-clean trees and such. If you don't -use Git you may use the alternative archive creation scripts in the next -section. - -Follow these steps assuming the current working directory is the root of git -working copy and you want to prepare distribution for the version x.y.z: - -1. Run "./build/tools/svn-find-native-eols.pl > ../eol-native" (if you have - an existing svn checkout, pass it to the script to make it run much faster, - but take care to have up to date sources in the working tree). - -2. Run "./build/tools/git-make-release x.y.z" to create source archives - ../wxWidgets-x.y.z.{7z,tar.bz2,zip} and wxWidgets_x.y.z_Headers.zip. - -3. Run "./build/tools/make-html-docs x.y.z" to create HTML documentation - archives ../wxWidgets-x.y.z.{tar.bz2,zip} - -4. This step must be done under Windows as it relies on having hhc.exe, the - Html Help compiler, in PATH: run the following commands - - cd docs\doxygen - regen.bat chm - cd out - zip ..\..\..\wxWidgets-x.y.z-docs-chm.zip wx.chm - -5. This step also must be done under Windows as it uses Inno Setup to produce - the .exe file and it also requires the CHM file built above: - - md x.y.z-sources - cd x.y.z-sources - 7z x ..\wxWidgets-x.y.z.7z - md docs\htmlhelp - cp ..\docs\doxygen\out\wx.chm docs\htmlhelp - set WXW_VER=x.y.z - iscc build\tools\wxwidgets.iss - - - -Instructions for the previous version of release scripts --------------------------------------------------------- - -NB: These scripts haven't been used since 2.8 series and may not work any longer! - -Currently our release system uses a Python 2.x script to generate releases. -The script requires Unix utilities such as tar, zip and unix2dos and thus must -be run either on Unix or using Cygwin on Windows. To generate a release, simply -run the following command: - -build/tools/create-archive.py --compression=all /path/to/output/dir - -This will produce zip, gzip and bzip archives of the tree (without -"compression" argument only .gz is made). Note that this commands produces huge -amounts of output so redirecting it to a file is recommended. - -To add a prefix to the release, such as RC1, the SVN revision, or a date, just -pass --postfix="postfix" to the script. More info on the options and their -possible values can be found by calling `create-archive.py --help`. - -IMPORTANT NOTE: You *must* run this script from a clean source tree, that is, - with no junk files in it or modifications. This is because the - release should be a pristine copy of the tree as of the time of - release. If you have legitimate modifications in the tree that need - to be in the release, commit them first. - -To generate the windows installer (.exe) and the documentation files (chm and htb formats) -run: - -build\tools\bld_chm_exe.bat - -which depends on the wxwidgets.iss file, and generates output in the %DAILY% directory. It -assumes a clean copy of the wxWidgets source tree in %INNO%. Temporary files will be generated -in the tree from which the batch file is run. It depends on doxygen, a number of gnu -win32 tools and Microsofts htmlhelp compiler. The wxwidgets.iss file should not need -editing, but you will want to check that the bld_chm_exe.bat has the correct version number. - - - -Uploading ---------- - -Upload the files to SourceForge. This can be done via the web interface or just -scp to sfusername,wxwindows@frs.sf.net:/home/frs/project/w/wx/wxwindows/x.y.z -The following files need to be uploaded: - - wxMSW-Setup-x.y.z.exe - wxWidgets-x.y.z.7z - wxWidgets-x.y.z.tar.bz2 - wxWidgets-x.y.z.zip - wxWidgets-docs-chm-x.y.z.zip - wxWidgets-docs-html-x.y.z.tar.bz2 - wxWidgets-docs-html-x.y.z.zip - -The file wxWidgets-x.y.z_Headers.7z should be uploaded to binaries -subdirectory as it's only useful when using pre-built binaries. - -You will need to use the web interface to mark the latest uploaded files as -being "default downloads" for the appropriate platforms (.zip or .exe for MSW, -.tar.bz2 for everything else) as otherwise SourceForge would continue to suggest -people to download old files. - -Next, update (at least the versions and SHA1 sums, but maybe more) and upload -docs/release_files.mdwn and docs/release_binaries.mdwn files. They need to be -renamed to README.md on SF to be shown when the directory is viewed, i.e. do: - - scp docs/release_files.mdwn \ - sfuser,wxwindows@frs.sf.net:/home/frs/project/w/wx/wxwindows/x.y.z/README.md - scp docs/release_binaries.mdwn \ - sfuser,wxwindows@frs.sf.net:/home/frs/project/w/wx/wxwindows/x.y.z/binaries/README.md - -And upload the change log too: - - scp docs/changes.txt \ - sfuser,wxwindows@frs.sf.net:/home/frs/project/w/wx/wxwindows/x.y.z - - -Also upload the files to the FTP mirror at ftp.wxwidgets.org (ask Chris for -access if you don't have it). - -Create http://docs.wxwidgets.org/x.y.z/ (ask Bryan to do it if not done yet). - - -Announcement ------------- - -Post docs/publicity/announce.txt at least to wx-announce@googlegroups.com and -to wx-users for the important releases. - -Submit a link to http://www.reddit.com/r/programming - -Submit to http://isocpp.org/blog/suggest - -For major releases, submit the announcement to http://slashdot.org/submission - -Update www.wxwidgets.org, usually a news item is enough but something more can -be called for for major releases. - -Modify the links at downloads/index.html to point to the new release. - -Also update docs/index.html for the minor or major (i.e. not micro) releases. - -Post to wxBlog if necessary. - -Announce on Google+/Twitter/whatever the person doing the release prefers (we -don't have "official" wxWidgets account, should we?). - - -Version updates ---------------- - -Trac: mark the milestone corresponding to the release as completed and add a -new version for it to allow reporting bugs against it and create the next -milestone (ask Vadim or Robin to do it or to get admin password). - -Run misc/scripts/inc_release to increment micro version, i.e. replace x.y.z -with x.y.z+1 (minor or major versions updates require manual intervention). - -Update the definition of the stable and release branches in -build/buildbot/config/include/defs.xml after a minor version change. +Please see index.txt diff --git a/docs/tech/tn0023.txt b/docs/tech/tn0023.txt deleted file mode 100644 index b88ff13abc..0000000000 --- a/docs/tech/tn0023.txt +++ /dev/null @@ -1,35 +0,0 @@ - Adding a new app/screenshot to the wxWidgets.org front page - ===================================== - -To add a new app/screenshot to the front page, you first will need to have the -following: - -1. The application Name -2. A URL for the application -3. A series of screenshots for the app - -Each screenshot should have a 300 pixel width. A height around 225 pixels is -preferred, but it's more important to keep the aspect ratio of the screenshot. -Screenshot format is not important, but the important thing is to use the format -that gives you the best ratio of picture compression and size. Also, please -make sure the screenshots all have the app name in them. - -Once you have the screenshots and info ready, take the following steps to -update the web site: - -1) Put the screenshots in /site-v2/images/front_screens - -2) Open /site-v2/index.php - -3) Look for the "$apps = array();" line. Below it will be a series of items, -which are the data used for each app shown in the front page screenshots. - -Add a new line at the bottom, with the following format: - -$apps[] = array(appname, appurl, array(screenshot1, screenshot2, ...)); - -The screenshot1, etc. filenames should not have any path to them. They should -just be the filename. The actual shown screenshot is chosen at random from -the list of screenshots, so order, etc. doesn't matter. - -Once you've done this, the new app w/screenshots should appear on the front page! \ No newline at end of file diff --git a/docs/tech/tn0024.txt b/docs/tech/tn0024.txt index d724d5efbb..03cb9b9653 100644 --- a/docs/tech/tn0024.txt +++ b/docs/tech/tn0024.txt @@ -1,54 +1 @@ - How to add a new XRC handler - ============================ - -0. Purpose ----------- - -This note describes what needs to be done to add a new XRC handler, i.e. add -support for loading the objects of some class wxFoo from XRC. - - -1. Implement the handler ------------------------- - -By convention, the XRC handler for a class wxFoo declared in wx/foo.h is called -wxFooXmlHandler and is declared in the file wx/xrc/xh_foo.h (this last rule -wasn't always respected in the past, however it's not a reason to not respect -it in the future). The steps for adding a new handler are: - -a) Add handler declaration in include/wx/xrc/xh_foo.h, it will usually be the - same as in the other files so you can get inspiration for your brand new - handler from e.g. wx/xrc/xh_srchctrl.h. Notice the use of wxUSE_FOO if wxFoo - is guarded by this symbol. - -b) Add implementation in src/xrc/xh_foo.cpp: again, it will be almost always - very similar to the existing controls. You will need to add support for - the control-specific styles. - - -2. Update the other files -------------------------- - -There are a few other files to update to make wxWidgets aware of the new -handler: - -a) Add the new files created above to build/bakefiles/files.bkl: search for - "xh_srchctrl" to see where you need to add them - -b) Add #include "wx/xrc/xh_foo.h" to wx/xrc/xh_all.h. - -c) Register the new handler in wxXmlResource::InitAllHandlers() in - src/xrc/xmlrsall.cpp - - -3. Update the sample --------------------- - -Demonstrate that the new handler works by adding a control using it to -samples/xrc/rc/controls.xrc. - - -=== EOF === - -Author: VZ - +Please see index.txt diff --git a/docs/tech/tn0025.txt b/docs/tech/tn0025.txt index 058084a9c1..03cb9b9653 100644 --- a/docs/tech/tn0025.txt +++ b/docs/tech/tn0025.txt @@ -1,127 +1 @@ - How to update a third party library to a newer version - ====================================================== - -0. Introduction ---------------- - -wxWidgets includes several third party libraries, i.e. libraries which are -used by wxWidgets and distributed with it but which we don't maintain nor even -modify, inasmuch as possible, ourselves. These libraries are developed by -their maintainers and from time to time we need to replace the versions used -by wxWidgets with newer versions. - - -1. Vendor branches ------------------- - -Normally all third party libraries should be managed using Subversion vendor -branches. I.e. we should have the latest version of the library under -/wx/wxWidgets/vendor directory in the repository. Currently only expat, libpng -and libtiff are handled like this, while libjpeg and zlib are not. Hopefully -these exceptions will disappear soon, the rest of this note assumes that we -are using a vendor branch for the library $(LIB). - -We also use $(OLD_VERSION) and $(VERSION) below for the current version of the -library and the version we are upgrading to. $(OLD_VERSION) can be determined -by doing - - svn ls https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB) - -as normally it's the latest version present in this directory. You can, of -course, also look at the library sources currently in the trunk to find out -its version. - - -NB: the instructions here are based on the Subversion documentation, see -http://svnbook.red-bean.com/en/1.6/svn.advanced.vendorbr.html for more -information about vendor branches. - - -2. Updating the current branch ------------------------------- - -The first thing to do is to checkout a pristine copy of the version currently -being used, e.g. - - cd /some/temp/directory - svn checkout https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB)/current $(LIB) - -Now delete all the old files: - - cd $(LIB) - find . -type f -not -path '*/.svn/*' -exec rm {} \; - -or, if you are using zsh, just - - rm **/*(.) - -Next, get the version of the library you are updating to and unpack it into -the same directory. Examine "svn status" output and add all the files with "?" -in the first column using "svn add" and delete all the files with "!" in the -first column using "svn rm". - -Finally commit and tag the new version: - - svn commit -m 'Update $(LIB) to $(VERSION).' - svn cp https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB)/current \ - https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB)/$(VERSION) \ - -m 'Tagging $(LIB) $(VERSION).' - -You can now do - - rm -rf /some/temp/directory/$(LIB) - -as it won't be needed any longer. - - -3. Merging the current branch ------------------------------ - -Now switch to wxWidgets checkout and run - - svn merge ^/wxWidgets/vendor/$(LIB)/$(OLD_VERSION) ^/wxWidgets/vendor/$(LIB)/current src/$(LIBDIR) - -Notice that you may need to escape the circumflexes with backslashes if they -are special for your shell. Also notice that the directory of the library may -be different from its name, e.g. we use libpng for the vendor branch but just -png for the name of the directory. - -Unless you are very lucky, the merge will result in conflicts and you will -need to resolve them by examining the differences -- this is the difficult -part. - -Once everything was resolved, test your changes. As building the third party -libraries is quite different between Unix and Windows, please do it under both -platforms. Under Windows it's enough to just build everything as usual as the -built-in libraries are used by default. Please build both static and dynamic -wxWidgets libraries as some problems arise only in one of those configurations. -Under Unix you need to configure with --with-$(LIB)=builtin option to ensure -that the newly updated built-in version of the library is used and not the -system version. If upgrading an image format library, please build and run the -image sample. In any case, run the unit tests to check that everything still -works. - -After testing and correcting the problems, simply commit your changes: - - svn commit -m 'Update $(LIB) to $(VERSION).' src/$(LIBDIR) - - -4. Special instructions for libpng ----------------------------------- - -We use a special hack for libpng as we want to prefix all its symbols with -"wx_" but don't want to use its build system which makes this easily possible -(perhaps we should, but for now we don't). So, when upgrading libpng, you need -to perform an extra step after merging the new version (and before committing -your changes): - -Create a temporary build directory and run libpng configure from it using ---with-libpng-prefix=wx_ option. Then run "make" (actually just "make png.lo" -is sufficient as we don't really need to build the library) to create -pnglibconf.h and pngprefix.h files in the build directory. And copy these -files to src/png subdirectory of the wxWidgets source tree, overwriting the -versions there. - -Notice that config.h generated by libpng configure is not used, we build it -without -DHAVE_CONFIG_H as it works just fine without it on any ANSI C system -(i.e. anywhere by now). +Please see index.txt