mars3142/wx_wherigo
1
0
Fork 0
Code Issues Pull Requests Wiki Activity

initial commit

Browse Source 
Signed-off-by: Peter Siegmund <mars3142@noreply.mars3142.dev>
This commit is contained in:
Peter Siegmund
2025-10-31 23:37:30 +01:00
commit bf6b52fd94
9654 changed files with 4035664 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

165
libs/wxWidgets-3.3.1/docs/contributing/about-platform-toolkit-and-library-names.md Normal file
View File

@@ -0,0 +1,165 @@
## 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.
The libraries use the following naming convention.
When an item of the name is empty, `'_'` or `'-'` are omitted.
*UNIX libraries* (configure, CMake on Linux/macOS/Cygwin):
libwx_$(toolkit)$(widgetset)u_$(flavour)_$(name)-$(version)-$(host).$(lib_extension)
*Windows libraries* (VS solution, makefile.gcc/vc, CMake on Windows, shared libraries on Windows):
wx$(toolkit)$(widgetset)$(version)u$(debug)_$(flavour)_$(name)_$(compiler)_$(arch)_$(vendor).$(lib_extension)
Where:
--------------------------------------------------------------------
`$toolkit` can currently be one of the following:
- `base`
- `msw`
- `gtk`, `gtk2`, `gtk3`, `gtk4`
- `osx_cocoa`, `osx_iphone`
- `x11`
- `dfb`
- `qt`
--------------------------------------------------------------------
`$widgetset` may be one of:
- `univ`
or empty if the widget set is the same as the toolkit.
--------------------------------------------------------------------
`$version` is a string encoding the major and minor version number,
separated by a dot on UNIX and without separator on Windows.
Windows shared libraries of development versions (odd minor releases)
contain the full version (major, minor, release).
On UNIX, the `$so_version` contains the release number.
Eg. for wxWidgets 3.1.5, `$version` is `315` for Windows shared libraries,
`31` for Windows static libraries, and `3.1` for UNIX libraries. And the
`$so_version` for UNIX libraries is `.5` and `.5.0.0`.
The rationale for this is that under UNIX-like systems it is desirable
that differently 'minor numbered' releases can be installed together,
meaning 3.0 apps can continue to work even if you migrate development
to the next stable or unstable release (eg. 3.2, 3.3), 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.ac for details on this).
--------------------------------------------------------------------
The `'u'` in the library names refers to "Unicode" build, which is now the only
supported one, but which used to be optional.
--------------------------------------------------------------------
`$debug` is set to `'d'` for the libraries using debug version of CRT and is empty
for release libraries. It is only really useful for the libraries created with MSVC,
as MSVC debug and release CRT are not ABI-compatible, but is also used by MinGW
(makefile.gcc, CMake) for consistency with MSVC builds. When using configure under
MSW or UNIX, it is always empty.
--------------------------------------------------------------------
`$flavour` is an optional name to identify the build. It is empty by default.
--------------------------------------------------------------------
`$name` is the name of the library. It is empty for the `'base'` library.
--------------------------------------------------------------------
`$compiler` is the used compiler, for example `'vc'` or `'gcc'`.
It is only added to shared libraries on Windows.
--------------------------------------------------------------------
`$arch` is used only when building with MSVC. It is empty for 32-bit builds and
`'x64'` for 64-bit builds. It is only added to shared libraries.
--------------------------------------------------------------------
`$vendor` is an optional name appended to the library name. It is only
added to shared libraries on Windows. It defaults to `'custom'` and is
empty for the official Windows binaries.
--------------------------------------------------------------------
`$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. On UNIX, it is most usually set
to `'.a'` for a static library and `'.so.$so_version'` for a shared library.
On Windows, it is `'.lib'` for a static or import MSVC library, `'.a'` for a
static or import GCC or clang library, and `'.dll'` for a shared library.
--------------------------------------------------------------------
`type` is used to indicate a shared or static build. On Windows, type is
`'dll'` for shared libraries and `'lib'` for static libraries.
On UNIX, type is empty for shared libraries and `'static'` for static libraries.
--------------------------------------------------------------------
## setup.h
The installed location of the library specific setup.h is also
determined by the values of these items. On UNIX they will be found in:
$(prefix)/lib/wx/include/$(host)-$(toolkit)$(widgetset)-unicode-$(type)-$(version)-$(flavour)/wx/setup.h
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).
For MSVC and gcc/vc makefile, the file is found in:
$(prefix)/lib/$(compiler)_$(arch)_$(type)/$(toolkit)$(widgetset)u$(debug)/wx/setup.h
--------------------------------------------------------------------
## wx-config
The port specific wx-config file for each library shall be named:
$(prefix)/lib/wx/config/$(host)-$(toolkit)$(widgetset)-unicode-$(type)-$(version)-$(flavour)
${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.

39
libs/wxWidgets-3.3.1/docs/contributing/about-version-numbers.md Normal file
View File

@@ -0,0 +1,39 @@
All about wxWidgets Version Numbers
===================================
## 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]
- configure.ac
- 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/mainpages/manual.h (just date) [NOT UPDATED AUTOMATICALLY]
- include/wx/version.h
- include/wx/osx/config_xcode.h
- samples/minimal/Info_cocoa.plist
- samples/minimal/CMakeListst.txt [major/minor only]
Do not forget to rebake everything after updating version.bkl!
## 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 [binary compatibility notes](binary-compatibility.md)

292
libs/wxWidgets-3.3.1/docs/contributing/binary-compatibility.md Normal file
View File

@@ -0,0 +1,292 @@
Binary Compatibility and wxWidgets
==================================
Purpose
-------
This is a broad technote covering all aspects of binary compatibility with
wxWidgets.
Releases
--------
General overview of releases can be found in [wxWidgets naming conventions](about-platform-toolkit-and-library-names.md),
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.8.x, 3.0.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 the section about `wxABI_VERSION`.
What kind of changes are NOT binary compatible
----------------------------------------------
[The KDE guide](https://community.kde.org/Policies/Binary_Compatibility_Issues_With_C%2B%2B)
is a good reference.
The changes that are NOT binary compatible:
- Adding a virtual function
- Changing the name of 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
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
`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 section Releases.
An example of using `wxABI_VERSION` is as follows for symbols
only in a 2.6.2 release:
```cpp
#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
```
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.
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:
https://ftp.gnu.org/old-gnu/Manuals/ld-2.9.1/html_node/ld_25.html
Or see chapter 5 of the 'Linker and Libraries Guide' for Solaris, available
online here:
https://docs.oracle.com/cd/E19120-01/open.solaris/819-0690/chapter5-84101/index.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
compiler.
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*;
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
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.

314
libs/wxWidgets-3.3.1/docs/contributing/how-to-add-class-documentation.md Normal file
View File

@@ -0,0 +1,314 @@
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 (currently Doxygen 1.8.8
is used) and Graphviz installed in your system (under Windows Graphviz
location should be in %PATH%).
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 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:
- use present tense verbs in 3rd person singular form to describe functions,
i.e. write "Returns the answer to life, universe and everything", rather than
the imperative mood used in Git commit message ("Return the answer ...").
- 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.doxygen.org/manual/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 nullptr 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. &amp; 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 `<b>...</b>`, `<tt>...</tt>`, `<em>...</em>`
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
...
<hr>
@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
...
*/

230
libs/wxWidgets-3.3.1/docs/contributing/how-to-add-files-to-build-system.md Normal file
View File

@@ -0,0 +1,230 @@
How to add new files and libraries to wxWidgets build system
============================================================
Regenerating makefiles
----------------------
wxWidgets uses the legacy 0.2 branch [Bakefile](https://www.bakefile.org) to
generate native makefiles.
Currently the latest version from legacy-0.2-branch must be used, so you need
to compile it from source, which requires Python 2 headers and libraries.
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.
You can also run Bakefile from a Docker or Podman container and avoid the need
to install it (expanding "$(wx)" to be the path to wx install):
docker run --rm -v $(wx):$(wx) -w `pwd`
ghcr.io/vslavik/bakefile:0.2 bakefile_gen
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 `<add-flags>` and `<del-flags>` directives
and use `bakefile_gen` instead of running bakefile directly.
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
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`.
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`.
Adding a new sample
-------------------
This is explained in details in `how-to-add-new-sample.md` file, please see
there.
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:
<set var="WXLIB_FOO">
<if cond="MONOLITHIC=='0'">$(mk.evalExpr(wxwin.mkLibName('foo')))</if>
</set>
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.ac and wx-config.in to contain information about
the library and needed linker flags:
* Add "foo" to `BUILT_WX_LIBS` in configure.ac.
* 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.ac.
* 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 `#pragma comment(lib, "foo")` (for all build configuration
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`.

63
libs/wxWidgets-3.3.1/docs/contributing/how-to-add-new-font-encoding.md Normal file
View File

@@ -0,0 +1,63 @@
How to add a new font encoding to wxWidgets
===========================================
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).
The recipe
----------
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:
- gs_encodings
- gs_encodingDescs
- 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 either.
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](how-to-write-unit-tests.md) 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.

70
libs/wxWidgets-3.3.1/docs/contributing/how-to-add-new-msvs-version.md Normal file
View File

@@ -0,0 +1,70 @@
How to add support for a new MSVS version
=========================================
MSVS versions
-------------
This is confusing because there are several of them:
- Marketing IDE/product version, which is the year of the release, e.g. 2019.
- Actual internal IDE version, visible in `Help|About` dialog, for example,
e.g. 16.1.4.
- Compiler version, visible in `cl /?` output, e.g. 19.21.27702.2. This version
also corresponds to the value of the predefined `_MSC_VER` symbol.
- Toolset version: this is similar to the compiler version, but uses different
format, e.g. it's 14x for compiler version 19, with `x` being 0, 1 or 2
depending on the minor compiler version (00, 14 or 21).
Moreover, historically, different IDE versions corresponded to different major
compiler versions, however this hasn't been the case any more for the last few
releases (2015, 2017, 2019 or 14, 15, 16 IDE versions) that all use the same
major compiler version (19) as they are ABI-compatible. Also, historically,
each compiler used its own toolset, but these last few versions can each use
any of 140, 141, 142 toolset.
wxWidgets uses the IDE version for the project/solution files (but notice that
project files are the same for all MSVS 201x versions) and the toolset version
for the names of build directories.
TODO list
---------
Here is a list of things that need to be done when adding support for the next
MSVS version:
- If the major compiler version changed, add a new `__VISUALCxx__` symbol to
`include/wx/compiler.h` (`xx` here are the first 2 digits of the toolset
version, i.e. basically correspond to the major compiler version, except
that 13 was skipped for superstitious reasons, see the comment in that file).
- Add `wxCOMPILER_PREFIX` definition for the new version to
`include/msvc/wx/setup.h`.
- Add the new solution file `build/msw/wx_vcNN.sln` (where `NN` is the internal
IDE version), typically by opening an existing solution in the new IDE and
letting it to update it.
- Add the new solution files `samples/samples_vcNN.sln`, `tests/test_vcNN.sln`
and `tests/test_gui_vcNN.sln` in a similar way.
- Add the new version to the instructions in `how-to-add-new-sample.md` in this
directory.
- Discard changes to the project files that were done by the IDE during the
update and instead update `build/msw/wx_config.props` and add a new condition
checking `VisualStudioVersion` value for choosing the value of
`PlatformToolset`.
- Update the lists of supported compiler versions in the different
documentation files (search for "Microsoft Visual C++" to find the places
that need updating):
- `README.md`
- `docs/doxygen/mainpages/introduction.h`
- `docs/msw/install.md`
- `docs/release.md`
- Update `build/tools/msvs/officialbuild.bat` to support the new toolset version
and also update `build/tools/msvs/buildall.bat` to call it with this new version
(these files are used to build the official binaries for the releases).
- If necessary, i.e. if the warning C4535 appears when compiling
`src/msw/main.cpp` with the new version, check that this warning is still
harmless, i.e. that catching Win32 exceptions still works correctly (this
can be tested with the "Crash" menu item in the except sample) and update
the version check in `include/wx/msw/seh.h` to suppress this warning for the
new version too.
- Update checks for `VISUALSTUDIOVERSION` in `build/bakefiles/common.bkl` to
take the new version into account.

94
libs/wxWidgets-3.3.1/docs/contributing/how-to-add-new-sample.md Normal file
View File

@@ -0,0 +1,94 @@
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.
2. "git 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. In particular, the Windows resource
specification should use the central `.rc` file, i.e. do not use
`<win32-res>` bakefile tag unless it is really necessary.
3. Create the make and project files:
- Create MSVS project for the sample and add it to the solution file:
* In the simplest case, run the following command, which requires some
version of Perl to be available, from the root of the wxWidgets source
tree:
./build/clone-minimal-vcxproj samples/foo/foo
* If you need to base the sample on some other project, e.g. console one
for a new non-GUI sample, you can alternatively run
./build/vcxproj-clone samples/console/console.vcxproj samples/foo/foo
* In either case, open the `samples/samples_vc17.sln` and move the new
project under the appropriate folder in the solution tree.
* The following one-liner can be used to update all the other solution files
(but you may also update them manually if you can't use this command,
which requires Unix-like environment):
$ for v in 14 15 16; do
git diff samples/samples_vc17.sln | \
sed "s/samples_vc17.sln/samples_vc${v}.sln/g" | \
git apply -v
done
- modify samples/samples.bkl (just copy an existing line)
- create `foo.bkl`, typically by just copying an existing bakefile from
another sample (`sed 's/minimal/foo/g' minimal.bkl > foo.bkl` is usually
enough, but you may need to add more `<wx-lib>` lines if your sample uses
anything not in the core lib)
- add `<wx-data>` element with the data files used by the sample that need
to be copied to its build directory, if any (see e.g.
`samples/image/image.bkl` for an example of using this tag).
- generate the makefiles for your sample using bakefile. For this you
need to:
- install bakefile (see `how-to-add-files-to-build-system.md`)
- 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<compiler>` to generate just the makefiles for the given
compiler (run `bakefile --help` to get the list of possible values).
Again, see `how-to-add-files-to-build-system.md` for more information.
4. Modify configure.ac Unix compilation:
- if the sample should only be built if `wxUSE_FOO` is enabled, locate
the test for `wxUSE_FOO = yes` in configure.ac and add a line
`SAMPLES_SUBDIRS="$SAMPLES_SUBDIRS foo"` under it
- if it should be always built, locate the line `if test $wxUSE_GUI = yes`
near the end of configure.ac and modify the assignment to
`SAMPLES_SUBDIRS` to include "foo" (put in alphabetical order)
After this, regenerate configure from configure.ac
by running "autoconf" on a Unix system in the corresponding directory.
5. Modify `build/cmake/samples/CMakeLists.txt` to include the sample in
CMake. Add a new line like this:
wx_add_sample(foo DEPENDS wxUSE_FOO)
Use `DATA` CMake variable if the sample uses any data files.
For a complete list of parameters to the `wx_add_sample()` function see
the description in `build/cmake/functions.cmake`.
6. 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.
7. 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.

119
libs/wxWidgets-3.3.1/docs/contributing/how-to-add-new-ui-bitmaps.md Normal file
View File

@@ -0,0 +1,119 @@
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:
- add #include line for your XPM file, e.g. #include "../../art/my_bmp.xpm"
- 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.

87
libs/wxWidgets-3.3.1/docs/contributing/how-to-add-new-wxUSE_XXX.md Normal file
View File

@@ -0,0 +1,87 @@
How to add a new `wxUSE_XXX` preprocessor constant
================================================
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`.
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`.
Files to update
---------------
The following files need to be modified when adding a new `wxUSE_FOO`:
- `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).
- `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.
- `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 them here too.
- `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.
- `configure.ac`
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 together with all the existing `WX_ARG_ENABLE`s.
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.
- `build/cmake/options.cmake`
To include the option in CMake, add a new line in the appropriate
section of `options.cmake`.
wx_option(wxUSE_FOO "enable FOO")
As an optional third parameter you may specify `OFF` when the option
should be disabled by default.
- `docs/doxygen/mainpages/const_wxusedef.h`
Add a brief description of the new constant.

48
libs/wxWidgets-3.3.1/docs/contributing/how-to-add-new-xrc-handler.md Normal file
View File

@@ -0,0 +1,48 @@
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:
- 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.
- 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:
- Add the new files created above to build/bakefiles/files.bkl: search for
"xh_srchctrl" to see where you need to add them
- Add #include "wx/xrc/xh_foo.h" to wx/xrc/xh_all.h.
- 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.

218
libs/wxWidgets-3.3.1/docs/contributing/how-to-release.md Normal file
View File

@@ -0,0 +1,218 @@
# Making a New wxWidgets Release
## Checking ABI Compatibility
For the stable (even) releases only, check that binary compatibility hasn't
been broken since the last stable release.
### Checking under Unix systems using `libabigail`.
Instructions:
1. Get [the tools](https://sourceware.org/libabigail/). Under Debian and
derived systems `apt install abigail-tools` can be used.
1. Build the old (vX.Y.Z-1) library with `-g` option, i.e. configure it
with `--enable-debug`. For convenience, let's assume it's built in "$old"
subdirectory.
1. Build the new (vX.Y.Z) library with the same options in "$new".
1. Create directories for temporary files containing the ABI dumps for the old
and new libraries: `mkdir -p ../compat/{$old,$new}`.
1. Run `abidw` on all libraries: `for l in $old/lib/*.so; do abidw $l
--out-file ../compat/$old/$(basename $l).abi; done` and the same thing with
the new libraries.
1. Run `abidiff` on each pair of produced dumps to generate HTML
reports: `for l in $old/*.abi; do abidiff $l -new $new/$(basename $l); done`.
1. If everything is good, update the ABI files in `$old` with the `$new` ones.
See also `build/elfabi/check_all.sh` which checks the ABI of the newly built
libraries and is simpler to use if there is no need to update the ABI files.
### Checking under MSW systems.
Manually check compatibility by building the widgets samples from the old tree
and then run it using the new DLLs.
## Requesting to Update the Translations
Post to wx-translators@googlegroups.com to ask to update the translations
before the release. This needs to be done some time before making it, of
course.
## Pre-Release Steps
Start by copying all the changes since the previous release to the change log
file as explained in the comment there.
Then update the files below. You can run `build/tools/pre-release.sh` to do
the straightforward changes like updating the dates and checksums
automatically, but please also review and update the contents of the README
and announcement text.
The Post-Release step of the previous release will have updated
the micro version of this release. If this release represents a major
or minor release, these changes will have to be performed manually at
this point.
Note that the best order depends on the release being prepared: for a
development release, `docs/publicity/announce.txt` contains the list of the
major changes since the last stable release and should be updated first, as
this part of it can then be copied verbatim to the corresponding section of
the README file. For the stable releases, it's probably more convenient to
update the README with the details of the changes first.
Here is the list of the files, for reference:
* Update `docs/readme.txt`: version needs to be changed, content updated.
* Update `docs/release.md`: also version and reset SHA-1 sums to zeroes.
* Update `docs/changes.txt`: update the date on the release line.
* Update the date in the manual (`docs/doxygen/mainpages/manual.h`).
* Update the release announcement post in `docs/publicity/announce.txt`.
* Update `docs/msw/binaries.md`: at least the version, but possibly also
the list of supported compilers.
Commit the changes and tag the release using your GPG key:
git tag -s -m 'Tag X.Y.Z release' vX.Y.Z
Don't overwrite existing tags. For non-final releases use e.g. `X.Y.Z-rc1`
instead of `X.Y.Z`.
## Creating Release On GitHub
Go to https://github.com/wxWidgets/wxWidgets/actions/workflows/make_release.yml
and use the "Run workflow" button to manually run this workflow for the
appropriate branch (either `master` or `3.2` currently). This will create a new
draft release that can be found in the release list or you can see its exact
URL in the output of the "Add Files to the Release" workflow step.
On the release page, use the "Edit" button to manually move the checksums at
the very end of the announcement text to their correct locations (i.e. replace
the all zero checksums with the actual ones).
Also review the announcement for correctness.
Build and upload the binaries to the existing release.
Finally, publish it.
## Update documentation
This requires being able to ssh to docs.wxwidgets.org, please ask Bryan if you
think you should be able to do it, but can't.
Once logged in, copy the contents of either `latest` or `stable` directory to
`public_html/x.y.z`, switch any links, such as `3.1` to point to `x.y.z` by
doing
$ cd ~/public_html
$ ln -sfn 3.y.z 3.y
and edit `~/public_html/index.html` to add the link to the new release to it.
If the docs must be generated from the tag itself, run the documentation
generation workflow on GitHub manually providing the tag before doing the
above.
Note that the docs web site currently uses Cloudflare for caching, which means
that it won't update for several hours after the change, unless you purge the
cache manually in the Cloudflare console (which requires an account).
## Announcement
Update https://www.wxwidgets.org:
* Update release information (at least `version` and `released`) in `_data/releases.yml`.
* Update the list of compilers used for making MSW binaries in
`downloads/index.md` if necessary (note that there is no need to update
anything else, the page will dynamically show the release files with the
specified prefixes).
* Add a news item. Usually a news item is enough but something
more can be called for major releases
* Push the changes (or create the PR with them) to GitHub. Note that this will
trigger the site rebuild which will fail if the release statistics are not
available yet, so make sure to publish the release on GitHub first (or wait
an hour for the next scheduled site rebuild to happen).
* If this is a new minor release, update `docs/index.md` to add a link to the
documentation for the new branch and update the existing links descriptions.
Post `docs/publicity/announce.txt` at least to wx-announce@googlegroups.com and
to wx-users.
Submit a link to https://www.reddit.com/r/cpp or r/programming (depending on
the release importance).
Submit to https://isocpp.org/blog/suggest (need to be logged in to do it).
For major releases, submit the announcement to https://slashdot.org/submission
## Post-Release Steps
* Update the SHA-1 sums in `docs/release.md` using the checksums from the release
announcement, then commit the changes.
* Mark the milestone corresponding to the release as completed at
https://github.com/wxWidgets/wxWidgets/milestones
* Update the roadmap at https://wxwidgets.org/develop/roadmap/ to at
least mention the new release there (the text of this page lives in
wxWidgets/website repository).
* Run `misc/scripts/inc_release` to increment micro version,
i.e. replace x.y.z with x.y.z+1. When changing another version component,
all the files updated by this script need to be changed manually.
* Update the C:R:A settings in `build/bakefiles/version.bkl` to C:R+1:A.
Then from the build/bakesfiles directory run
bakefile_gen
and from the root directory run
autoconf
or, if you're not using Debian Stable version of autoconf, see the instructions
in `build/tools/autoconf/README.md` for regenerating configure on a different
system.
* Restore the description of the Git notes use and create a skeleton section
for the next release in `docs/changes.txt`.
## MSW Visual Studio Official Builds
To build official x86 and x64 shared binaries the following are prerequisites:
- Visual Studio 2008, 2010, 2012, 2013 and 2015
- Windows SDK 6.1, 7.1 (required for x64 builds for Visual Studio 2008, 2010)
- 7z (required for packaging the files)
- fciv (required for generating the checksums)
The VSxxxCOMNTOOLS environment variables are used to locate the tools required
for Visual Studio 2012, 2013 and 2015. There are no Microsoft defined variables
for the SDKs used for Visual Studio 2008 and 2010. The build will look for the
following environment variables for the Visual Studio 2008 and 2010 SDK tools:
WINDOWS61SDK
WINDOWS71SDK
If either of these are blank they are set to the default install location.
To build binaries for a single compiler, open a command prompt (for Visual
Studio 2008 only an SDK 6.1 developer's command prompt must be used),
cd to the build\tools\msvs folder and run the batch file 'officialbuild'
with the vcXXX version number:
Visual Studio 2008 vc90
Visual Studio 2010 vc100
Visual Studio 2012 vc110
Visual Studio 2014 vc120
Visual Studio 2015 vc14x
The Visual Studio 2015, 2017, 2019 and 2022 are binary compatible, allowing the
vc14x binary to be used with any of them.
This will build all of the x86 and x64 binaries for the selected compiler version,
package them in 7z files and calculate the checksums. The 7z files and the
checksums are output to the build\msw\packages folder.
All of the compiler packages can be built at the same time by executing the
build\tools\msvs\buildall.bat file from a command prompt. Each build will be
launched in its own shell.

129
libs/wxWidgets-3.3.1/docs/contributing/how-to-update-third-party-library.md Normal file
View File

@@ -0,0 +1,129 @@
How to update a third party library to a newer version
======================================================
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.
Submodules
----------
All third party libraries are managed using Git submodules. This includes
3rdparty/catch and expat, jpeg, png, tiff and zlib subdirectories of src.
As always with submodules, updating a library involves updating its sources in
the submodule, pushing this submodule out and then committing the changes in
the top-level repository.
Updating the submodule
----------------------
All submodules use `master` branch for the upstream master and `wx` for the
version used by wxWidgets. To update the latter, just merge the appropriate
commit from master into `wx`, e.g.
$ cd src/expat
$ git checkout wx
$ git merge R_x_y_z # For the latest x.y.z release
After resolving any conflicts, commit the result.
Special instructions for specific libraries
-------------------------------------------
Some libraries, notably those for which we store the generated build files in
our submodules, require extra actions to be undertaken after merging with the
upstream:
## libexpat
Run `buildconf.sh` to update the generated files and commit the changes.
## jpeg
There is no upstream repository available with the latest version. So download
and commit the releases from https://www.ijg.org/files/.
## 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 pnglibconf.h pngprefix.h`
to create these files in the build directory. Next, search for the line
containing `PNG_ZLIB_VERNUM` in the `pnglibconf.h` and set it to 0 to disable
zlib version checks (this looks dangerous but seems to be unavoidable with the
current build system). And then, finally, 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).
## libtiff
The forked upstream shown in github is incorrect. It is based on the official
TIFF repository https://gitlab.com/libtiff/libtiff.
Run `autogen.sh` to update the generated files and commit the changes.
Update `tif_config.h` and `tifconf.h` with the updated entries from their `.in` files.
Update the version numbers in `tiffvers.h`.
## zlib
Check for the newly added public systems in `zlib.map` and update `zconf.h` to
include if necessary -- at least with zlib 1.2.12 release this file wasn't
updated at all in the upstream version, resulting in problems such as #22280.
If `zconf.h` is updated, you probably already had to resolve the conflicts in
it, as our file differs from the upstream version due to having the changes
from [Z_PREFIX PR](https://github.com/madler/zlib/pull/323) included in it.
## pcre2
The forked upstream shown in github is incorrect. It is based on the official
PCRE2 repository https://github.com/PCRE2Project/pcre2.
You might need to use `git merge --allow-unrelated-histories`.
Updating the main repository
----------------------------
If there are any changes to the source files used by the library, update the
corresponding `build/bakefiles/$lib.bkl` file (e.g. `expat.bkl` for Expat) and
rerun bakefile to regenerate most of the makefiles and project files. Currently
you will need to update `build/msw/wx_wx$lib.vcxproj{,.filters}` files
manually.
After updating the `bkl` file, run `build/osx/makeprojects.py` to generate
the Xcode projects.
Commit these changes and the changes to the submodule itself, but don't push
them to GitHub yet.
Test and push
-------------
The updates need to be tested under MSW and under Unix using
`--disable-sys-libs` configure option.
If everything seems to work, push the updated branch out. Notice that you may
want to use the ssh GitHub repository URL instead of the default (because more
convenient for checking them out) HTTPS one:
$ git push --set-upstream git@github.com:wxWidgets/libexpat.git wx
Finally, create a PR to let the CI builds to run and test changes too. If no
problems are found, merge the PR as usual.

125
libs/wxWidgets-3.3.1/docs/contributing/how-to-write-unit-tests.md Normal file
View File

@@ -0,0 +1,125 @@
How to write unit tests for wxWidgets
=====================================
wxWidgets unit tests use [Catch](http://catch-lib.net/) framework. It is
included in wxWidgets as a submodule, so you will need to run
$ git submodule update --init 3rdparty/catch
to get it before the first use. Catch is header-only and doesn't need to be
compiled.
Building the tests
------------------
Before starting modifying the tests, please make sure you can build the
existing tests. This requires having built the library itself successfully
first and the way to build the test must correspond to the way you used to
build the library:
- When using MSVS under MSW: just open the provided `tests/test_vcX.sln` (for
non-GUI tests) or `tests/test_gui_vcX.sln` (for the GUI ones) solution file
(where `X` corresponds to the version of MSVS you use, e.g. 16 for MSVS 2019)
and build it in the configuration of your choice.
- When using configure under Unix or in a Unix-like environment, such as MSYS:
go to the `tests` subdirectory under the _build_ directory (i.e. the
directory where you ran configure, not the one in the source tree) and run
`make test` (non-GUI tests) or `make test_gui` (GUI ones) to build.
- When using CMake, add `-DwxBUILD_TESTS=ALL` (or `=CONSOLE_ONLY` for non-GUI tests
only) to the command line arguments, or choose the desired `wxBUILD_TESTS`
option in `cmake-gui`.
- When using `makefile.vc` or `makefile.gcc` under MSW to build the libraries,
use the same makefile under `tests` to build the tests.
Once the tests were built successfully, you can run them to check that
everything works correctly by simply launching the corresponding test binary.
See the last subsection for more details about running the tests.
Testing with Catch
------------------
**WARNING**: Most of the existing tests are currently still written in the
CppUnit style, please do _not_ follow them when writing new tests, the old
style is too complex and unnecessary.
Writing tests with Catch is almost embarrassingly simple: you need to just
add a new test case and use Catch assertion macros inside it, e.g.
TEST_CASE("MyNewTest", "[my][new][another-tag]")
{
wxString s("Hello, world!");
CHECK( s.BeforeFirst(",") == "Hello" );
CHECK( s.AfterLast(" ") == "world!" );
}
This is all, the new test will be automatically run when you run the full test
suite or you can run just it using
$ ./test MyNewTest
(see below for more about running tests).
See [Catch tutorial](https://github.com/philsquared/Catch/blob/v1.11.0/docs/tutorial.md)
for more information.
Tests physical structure
------------------------
All (i.e. both GUI and non-GUI) unit tests are under `tests` subdirectory. When
adding a new test, try to find an existing file to add it to. If there are no
applicable files, try to add a new file to an existing directory. If there is
no applicable directory either, create a new one and put the new file there
(i.e. do _not_ put new files directly under `tests`). If your test is small,
consider adding it to `tests/misc/misctests.cpp`.
If you add a new file, you need to update `tests/test.bkl` and add a
`<sources>` tag for your new file.bkl. Make sure it's in the correct section:
the one starting `<exe id="test_gui"` for a gui test, the one starting `<exe
id="test" template="wx_sample_console` otherwise. After modifying this file,
rerun bakefile to regenerate the tests make- and project files:
$ cd build/bakefiles
$ bakefile_gen -b ../../tests/test.bkl
Writing GUI-specific tests
--------------------------
`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
`tests/controls/buttontest.cpp`. After simulating some user input always
call `wxYield()` to allow event processing. When writing a test using
`wxUIActionSimulator` wrap it in `#if wxUSE_UIACTIONSIMULATOR` block.
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.
Running the tests
-----------------
Run the main test suite by using the command `test` for the console tests,
or `test_gui` for the GUI ones. With no arguments, all the default set of tests
(all those registered without `[hide]` tag) are run.
To list the test suites without running them use `-l` command-line option.
To run a particular test case, use `./test NameTestCase`. To run all tests
using the specified tag, use `./test [tag_name]` (the square brackets may need
to be escaped from your shell).

52
libs/wxWidgets-3.3.1/docs/contributing/translators-guide.md Normal file
View File

@@ -0,0 +1,52 @@
wxWidgets translator guide
==========================
This note is addressed to wxWidgets translators.
First of all, here is what you will need:
1. GNU gettext package
- For Unix systems you can download gettext-0.xx.yy.tar.gz from any GNU
mirror (RPMs and DEBs are also available from the usual places)
- For Windows you can download the precompiled binaries from
www.wxwidgets.org or install [Poedit](https://poedit.net/) and add
`<installdir>/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:
- For Unix systems, this is done in `locale/Makefile` using the standard `find`
command and `xargs` which is installed on almost all modern Unices.
- For Win32 systems you can use Cygwin, MSYS or WSL.
3. Access to the git repository 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 (which is updated from time to time by running
`make wxstd.pot` in the `locale` subdirectory) 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.

68
libs/wxWidgets-3.3.1/docs/contributing/wxmsw-contributor-guide.md Normal file
View File

@@ -0,0 +1,68 @@
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 `<windows.h>` or `<commctrl.h>` 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 <commdlg.h>` and
`<shlobj.h>` 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. Utility classes
---------------------------
wxWidgets provides a couple of useful (mostly undocumented) classes making
Windows API easier to work with.
Please whenever possible do not use raw pointers for BSTR, COM interfaces
or task memory, use the appropriate RAII wrapper instead (see below).
Grep wxWidgets source code for the class name to see how it is to be used.
*wxBasicString*: for `BSTR`, in `"wx/msw/ole/oleutils.h"`
*wxCOMPtr*: simplistic smart pointer for COM interfaces, in `"wx/msw/private/comptr.h"`
*wxCoTaskMemPtr*: smart pointer for memory allocated/freed with `CoTaskMem{Alloc/Free}()`,
in `"wx/msw/private/cotaskmemptr.h"`
*wxSafeArray*: for `SAFEARRAY`, in `"wx/msw/ole/safearray.h"`
3. 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.