Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'master' into web-request

Browse Source 
Merge with the latest master in preparation for merging into master.

Rebake to resolve conflicts in generated files.
This commit is contained in:
Vadim Zeitlin
2020-12-12 17:44:45 +01:00
parent 68cbd54db0 86a3578a11
commit 6bdab7b3c8
3934 changed files with 147571 additions and 96246 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/doxygen/overviews/backwardcompatibility.h
View File

@@ -108,7 +108,7 @@ compatible but can also be binary compatible.
Binary compatibility makes it possible to get the maximum benefit from using
shared libraries, also known as dynamic link libraries (DLLs) on Windows or
dynamic shared libraries on OS X.
dynamic shared libraries on macOS.
For example, suppose several applications are installed on a system requiring
wxWidgets 2.6.0, 2.6.1 and 2.6.2. Since 2.6.2 is backward compatible with the

2
docs/doxygen/overviews/bitmap.h
View File

@@ -82,7 +82,7 @@ XPM nor BMP formats are appropriate as they don't have support for alpha and
another format, typically PNG, should be used. wxWidgets provides a similar
helper for PNG bitmaps called wxBITMAP_PNG() that can be used to either load
PNG files embedded in resources (meaning either Windows resource section of the
executable file or OS X "Resource" subdirectory of the application bundle) or
executable file or macOS "Resource" subdirectory of the application bundle) or
arrays containing PNG data included into the program code itself.
@see @ref group_class_gdi

12
docs/doxygen/overviews/bookctrl.h
View File

@@ -41,12 +41,12 @@ The mapping consists of:
@beginTable
@row2col{ ::wxBookCtrl, wxChoicebook or wxNotebook }
@row2col{ @c wxEVT_COMMAND_BOOKCTRL_PAGE_CHANGED,
@c wxEVT_COMMAND_CHOICEBOOK_PAGE_CHANGED or
@c wxEVT_COMMAND_NOTEBOOK_PAGE_CHANGED }
@row2col{ @c wxEVT_COMMAND_BOOKCTRL_PAGE_CHANGING,
@c wxEVT_COMMAND_CHOICEBOOK_PAGE_CHANGING or
@c wxEVT_COMMAND_NOTEBOOK_PAGE_CHANGING }
@row2col{ @c wxEVT_BOOKCTRL_PAGE_CHANGED,
@c wxEVT_CHOICEBOOK_PAGE_CHANGED or
@c wxEVT_NOTEBOOK_PAGE_CHANGED }
@row2col{ @c wxEVT_BOOKCTRL_PAGE_CHANGING,
@c wxEVT_CHOICEBOOK_PAGE_CHANGING or
@c wxEVT_NOTEBOOK_PAGE_CHANGING }
@row2col{ @c EVT_BOOKCTRL_PAGE_CHANGED(id\, fn),
@c EVT_CHOICEBOOK_PAGE_CHANGED(id, fn) or
@c EVT_NOTEBOOK_PAGE_CHANGED(id, fn) }

10
docs/doxygen/overviews/cmake.md
View File

@@ -5,7 +5,7 @@ CMake Overview {#overview_cmake}
CMake allows building wxWidgets on various platforms with your preferred build
system.
Most linux distributions contain CMake as a package on Windows and OS X you can
Most linux distributions contain CMake as a package on Windows and macOS you can
download an installer at the [CMake Page](https://cmake.org).
Using the CMake GUI {#cmake_gui}
@@ -26,11 +26,11 @@ Using the CMake Command Line {#cmake_cli}
2. Change into the created folder
3. Run `cmake -G "Unix Makefiles" path_to_wxWidgets_root`
4. After that you can run `cmake --build .` to start the build process or
directly use your choosen build system.
directly use your chosen build system.
Run `cmake --help` to see a list of available generators on your platform.
These can than be specified using the -G command line option. On Windows it
is recommended to use Visual Studio and on OS X Xcode is recommended.
is recommended to use Visual Studio and on macOS Xcode is recommended.
Various build options can be specified using -D see
[available options](#cmake_options).
@@ -64,7 +64,7 @@ or specified via the -D command line option when running the cmake command.
Option Name | Type | Default | Description
------------------------- | ----- | ------- | ----------------------------
wxBUILD_SHARED | BOOL | ON | Build shared libraries
wxBUILD_SHARED | BOOL | ON | Build shared or static libraries
wxBUILD_TESTS | STRING | OFF | CONSOLE_ONLY, ALL or OFF
wxBUILD_SAMPLES | STRING | OFF | SOME, ALL or OFF
wxBUILD_DEMOS | BOOL | OFF | Build demo applications
@@ -122,5 +122,5 @@ Your *CMakeLists.txt* would look like this:
...
add_subdirectory(libs/wxWidgets)
add_executable(myapp myapp.cpp)
target_link_libraries(myapp net core base)
target_link_libraries(myapp wx::net wx::core wx::base)
~~~

2
docs/doxygen/overviews/customwidgets.h
View File

@@ -12,7 +12,7 @@
@tableofcontents
Typically combining the existing @ref group_class_ctrl controls in wxDialogs
and wxFrames is sufficient to fullfill any GUI design. Using the wxWidgets
and wxFrames is sufficient to fulfill any GUI design. Using the wxWidgets
standard controls makes your GUI looks native on all ports and is obviously
easier and faster.

2
docs/doxygen/overviews/datetime.h
View File

@@ -106,7 +106,7 @@ just @c wxDateTime::Now() + wxDateSpan::Month()).
@section overview_datetime_arithmetics Date Arithmetics
@section overview_datetime_arithmetics Date Arithmetic
Many different operations may be performed with the dates, however not all of
them make sense. For example, multiplying a date by a number is an invalid

2
docs/doxygen/overviews/debugging.h
View File

@@ -21,7 +21,7 @@ debugging. Both assertions and debug logging are also used by wxWidgets itself
so you may encounter them even if you don't use either of these features
yourself.
@see wxLog, @ref group_funcmacro_log, @ref group_funcmacro_debug
@see wxLog, @ref group_funcmacro_log, @ref group_funcmacro_debug

2
docs/doxygen/overviews/docview.h
View File

@@ -86,7 +86,7 @@ use Wx ':docview'; # import constants (optional)
@endcode
@endWxPerlOnly
@see @ref group_class_docview,
@see @ref group_class_docview,

114
docs/doxygen/overviews/eventhandling.h
View File

@@ -98,10 +98,11 @@ First define one or more <em>event handlers</em>. They
are just simple methods of the class that take as a parameter a
reference to an object of a wxEvent-derived class and have no return value (any
return information is passed via the argument, which is why it is non-const).
You also need to insert a macro
You also need to insert a line with the macro indicating that the class uses an
event table, like this:
@code
wxDECLARE_EVENT_TABLE()
wxDECLARE_EVENT_TABLE();
@endcode
somewhere in the class declaration. It doesn't matter where it appears but
@@ -132,7 +133,7 @@ private:
// obligation to do that; this one is an event handler too:
void DoTest(wxCommandEvent& event);
wxDECLARE_EVENT_TABLE()
wxDECLARE_EVENT_TABLE();
};
@endcode
@@ -224,7 +225,7 @@ global scope as with the event tables), call its Bind<>() method like this:
@code
MyFrame::MyFrame(...)
{
Bind(wxEVT_COMMAND_MENU_SELECTED, &MyFrame::OnExit, this, wxID_EXIT);
Bind(wxEVT_MENU, &MyFrame::OnExit, this, wxID_EXIT);
}
@endcode
@@ -323,7 +324,7 @@ MyFrameHandler myFrameHandler;
MyFrame::MyFrame()
{
Bind( wxEVT_COMMAND_MENU_SELECTED, &MyFrameHandler::OnFrameExit,
Bind( wxEVT_MENU, &MyFrameHandler::OnFrameExit,
&myFrameHandler, wxID_EXIT );
}
@endcode
@@ -345,7 +346,7 @@ void HandleExit( wxCommandEvent & )
MyFrame::MyFrame()
{
Bind( wxEVT_COMMAND_MENU_SELECTED, &HandleExit, wxID_EXIT );
Bind( wxEVT_MENU, &HandleExit, wxID_EXIT );
}
@endcode
@@ -366,7 +367,7 @@ MyFunctor myFunctor;
MyFrame::MyFrame()
{
Bind( wxEVT_COMMAND_MENU_SELECTED, myFunctor, wxID_EXIT );
Bind( wxEVT_MENU, myFunctor, wxID_EXIT );
}
@endcode
@@ -376,7 +377,7 @@ separate functor class:
@code
MyFrame::MyFrame()
{
Bind(wxEVT_COMMAND_MENU_SELECTED,
Bind(wxEVT_MENU,
[](wxCommandEvent&) {
// Do something useful
},
@@ -406,7 +407,7 @@ MyFrame::MyFrame()
{
function< void ( wxCommandEvent & ) > exitHandler( bind( &MyHandler::OnExit, &myHandler, _1 ));
Bind( wxEVT_COMMAND_MENU_SELECTED, exitHandler, wxID_EXIT );
Bind( wxEVT_MENU, exitHandler, wxID_EXIT );
}
@endcode
@@ -427,7 +428,7 @@ MyFrame::MyFrame()
function< void ( wxCommandEvent & ) > exitHandler(
bind( &MyHandler::OnExit, &myHandler, EXIT_FAILURE, _1, "Bye" ));
Bind( wxEVT_COMMAND_MENU_SELECTED, exitHandler, wxID_EXIT );
Bind( wxEVT_MENU, exitHandler, wxID_EXIT );
}
@endcode
@@ -614,7 +615,7 @@ custom event types.
Finally, you will need to generate and post your custom events.
Generation is as simple as instancing your custom event class and initializing
its internal fields.
For posting events to a certain event handler there are two possibilities:
For posting events to a certain event handler there are two possibilities:
using wxEvtHandler::AddPendingEvent or using wxEvtHandler::QueueEvent.
Basically you will need to use the latter when doing inter-thread communication;
when you use only the main thread you can also safely use the former.
@@ -675,13 +676,15 @@ void MyWindow::SendEvent()
Under certain circumstances, you must define your own event class e.g., for
sending more complex data from one place to another. Apart from defining your
event class, you also need to define your own event table macro if you want to
use event tables for handling events of this type.
event class, you also need to define your own event table macro if you still
need to use event tables (now considered legacy) for handling events of this type.
See ChessBoardEvent in the event sample for a full working implementation
of a new wxEvent-derived class.
Here is an example:
Here is a simple example:
@code
// define a new event class
// create a new event class derived from wxEvent
class MyPlotEvent: public wxEvent
{
public:
@@ -701,40 +704,51 @@ private:
const wxPoint m_pos;
};
// we define a single MY_PLOT_CLICKED event type associated with the class
// above but typically you are going to have more than one event type, e.g. you
// could also have MY_PLOT_ZOOMED or MY_PLOT_PANNED &c -- in which case you
// would just add more similar lines here
wxDEFINE_EVENT(MY_PLOT_CLICKED, MyPlotEvent);
// We use a single myEVT_PLOT_CLICKED event type associated with the class
// above but often you are going to have more than one event type, e.g. you
// could also have myEVT_PLOT_ZOOMED or myEVT_PLOT_PANNED etc. -- in which case
// you would just add more similar lines here.
//
// Note that this macro, as all declarations, should be in the header, and
// there should be a matching definition macro in some source file (see
// wxDEFINE_EVENT below).
wxDECLARE_EVENT(myEVT_PLOT_CLICKED, MyPlotEvent);
// if you want to support old compilers you need to use some ugly macros:
// --- Skip this part if you're only going to use Bind() (as recommended) ---
// The following typedef and macro are needed only when the new event class
// still needs to be used with the legacy approach to handling events - event
// table macros or Connect() - to cast the type of a function handling it to
// the type expected by the legacy event handling machinery.
typedef void (wxEvtHandler::*MyPlotEventFunction)(MyPlotEvent&);
#define MyPlotEventHandler(func) wxEVENT_HANDLER_CAST(MyPlotEventFunction, func)
// if your code is only built using reasonably modern compilers, you could just
// do this instead:
#define MyPlotEventHandler(func) (&func)
// If the new event is to be used with event tables, a macro for creating
// event table entries for the new event type must be defined.
#define EVT_PLOT_CLICKED(id, func) \
wx__DECLARE_EVT1(myEVT_PLOT_CLICKED, id, MyPlotEventHandler(func))
// finally define a macro for creating the event table entries for the new
// event type
//
// remember that you don't need this at all if you only use Bind<>() and that
// you can replace MyPlotEventHandler(func) with just &func unless you use a
// really old compiler
#define MY_EVT_PLOT_CLICK(id, func) \
wx__DECLARE_EVT1(MY_PLOT_CLICKED, id, MyPlotEventHandler(func))
// --- End of the part which is only relevant when using event tables ---
// example of code handling the event (you will use one of these methods, not
// both, of course):
// Up until now, we only had declarations that would typically appear in a
// header file. Starting from now we have the definitions, which must occur
// only once in the program and so need to be in a source file.
// This defines the event type declared above. If you use multiple event types,
// you need to do it for each of them.
wxDEFINE_EVENT(myEVT_PLOT_CLICKED, MyPlotEvent);
// example of code handling the event (you will use one of these methods,
// not both, of course):
wxBEGIN_EVENT_TABLE(MyFrame, wxFrame)
EVT_PLOT(ID_MY_WINDOW, MyFrame::OnPlot)
EVT_PLOT_CLICKED(ID_MY_WINDOW, MyFrame::OnPlot)
wxEND_EVENT_TABLE()
MyFrame::MyFrame()
{
Bind(MY_PLOT_CLICKED, &MyFrame::OnPlot, this, ID_MY_WINDOW);
Bind(myEVT_PLOT_CLICKED, &MyFrame::OnPlot, this, ID_MY_WINDOW);
}
void MyFrame::OnPlot(MyPlotEvent& event)
@@ -746,7 +760,7 @@ void MyFrame::OnPlot(MyPlotEvent& event)
// example of code generating the event:
void MyWindow::SendEvent()
{
MyPlotEvent event(MY_PLOT_CLICKED, GetId(), wxPoint(...));
MyPlotEvent event(myEVT_PLOT_CLICKED, GetId(), wxPoint(...));
event.SetEventObject(this);
ProcessWindowEvent(event);
}
@@ -864,6 +878,32 @@ If you use wxNewId() consistently in your application, you can be sure that
your identifiers don't conflict accidentally.
@subsection overview_events_with_mouse_capture Event Handlers and Mouse Capture
Some events are generated in response to a user action performed using the
mouse and, often, the mouse will be captured (see wxWindow::CaptureMouse()) by
the window generating the event in this case. This happens when the user is
dragging the mouse, i.e. for all events involving resizing something (e.g. @c
EVT_SPLITTER_SASH_POS_CHANGING), but also, perhaps less obviously, when
selecting items (e.g. @c EVT_LIST_ITEM_SELECTED).
When the mouse is captured, the control sending events will continue receiving
all mouse events, meaning that the event handler can't do anything relying on
getting them in any other window. Most notably, simply showing a modal dialog
won't work as expected, as the dialog won't receive any mouse input and appear
unresponsive to the user.
The best solution is to avoid showing modal dialogs from such event handlers
entirely, as it can be jarring for the user to be interrupted in their workflow
by a dialog suddenly popping up. However if it's really indispensable to show a
dialog, you need to forcefully break the existing mouse capture by capturing
(and then releasing, because you don't really need the capture) it yourself:
@code
dialog.CaptureMouse();
dialog.ReleaseMouse();
@endcode
@subsection overview_events_custom_generic Generic Event Table Macros
@beginTable

2
docs/doxygen/overviews/grid.h
View File

@@ -84,6 +84,7 @@ Here is a list of classes related to wxGrid:
number.
@li wxGridCellBoolRenderer: Renderer showing the cell as checked or unchecked
box.
@li wxGridCellDateRenderer: Renderer showing the cell as date.
@li wxGridCellEditor: Base class for objects used to edit the cell value.
@li wxGridCellStringEditor: Editor for cells containing text strings.
@li wxGridCellNumberEditor: Editor for cells containing integer numbers.
@@ -91,6 +92,7 @@ Here is a list of classes related to wxGrid:
@li wxGridCellBoolEditor: Editor for boolean-valued cells.
@li wxGridCellChoiceEditor: Editor allowing to choose one of the predefined
strings (and possibly enter new one).
@li wxGridCellDateEditor: Editor for cells containing dates without time component.
@li wxGridEvent: The event sent by most of wxGrid actions.
@li wxGridSizeEvent: The special event sent when a grid column or row is
resized.

4
docs/doxygen/overviews/helloworld.h
View File

@@ -15,6 +15,10 @@ This page shows a very simple wxWidgets program that can be used as a skeleton
for your own code. While it does nothing very useful, it introduces a couple of
important concepts and explains how to write a working wxWidgets application.
Note that this simple example creates the UI entirely from C++ code which is
fine for a simple example, but more realistic examples will typically define
their UI at least partially in @ref overview_xrc "XRC resource files".
First, you have to include wxWidgets' header files, of course. This can be done
on a file by file basis (such as @c wx/window.h) or using one global include
(@c wx/wx.h) which includes most of the commonly needed headers (although not

149
docs/doxygen/overviews/high_dpi.md Normal file
View File

@@ -0,0 +1,149 @@
High DPI Support in wxWidgets {#overview_high_dpi}
=============================
[TOC]
Introduction
============
Many modern displays have way more pixels on the same surface than used to be
the norm, resulting in much higher values of DPI (dots, i.e. pixels, per inch)
than the traditionally used values. This allows to render texts, or geometric
shapes in general much more smoothly.
As an illustration here are two scaled up views of the same text in 11 pt
Helvetica using up the same space on screen. First on an original Mac display
at 72 dpi, then on a High DPI Display, called "Retina" by Apple with twice as
many pixels in both dimensions (144 dpi), thus 4 times the number of pixels on
the same surface. Using these the contours are much more detailed.
![11 pt Helvetica at 72 DPI](overview_highdpi_text_72.png)
![11 pt Helvetica at 144 DPI](overview_highdpi_text_144.png)
To the user the DPI is typically expressed using a scaling factor, by which the
baseline DPI value is multiplied. For example, MSW systems may use 125% or 150%
scaling, meaning that they use DPI of 120 or 144 respectively, as baseline DPI
value is 96. Similarly, Linux systems may use "2x" scaling, resulting in DPI
value of 192. Macs are slightly different, as even they also may use "2x"
scaling, as in the example above, the effective DPI corresponding to it is 144,
as the baseline value on this platform is 72.
The Problem with High DPI Displays
----------------------------------
If high DPI displays were treated in the same way as normal ones, existing
applications would look tiny of them. For example, a square window 500 pixels
in size would take half of a standard 1920×1080 ("Full HD") display vertically,
but only a quarter on a 3840×2160 ("4K UHD") display. To prevent this from
happening, most platforms automatically scale the windows by the scaling
factor, defined above, when displaying them on high DPI displays. In this
example, scaling factor is 2 and so the actual size of the window on screen
would become 1000 when automatic scaling is in effect.
Automatic scaling is convenient, but doesn't really allow the application to
use the extra pixels available on the display. Visually, this means that the
scaled application appears blurry, in contrast to sharper applications using
the full display resolution, so a better solution for interpreting pixel values
on high DPI displays is needed: one which allows to scale some pixel values
(e.g. the total window size), but not some other ones (e.g. those used for
drawing, which should remain unscaled to use the full available resolution).
Pixel Values in wxWidgets
=========================
Logical and Device-Independent Pixels
-------------------------------------
Some systems like eg Apple's OSes automatically scale all the coordinates by
the DPI scaling factor, however not all systems supported by wxWidgets do it --
notably, MSW does not. This means that **logical pixels**, in which all
coordinates and sizes are expressed in wxWidgets API, do _not_ have the same
meaning on all platforms when using high DPI displays. So while on macOS you
can always pass in a size of (500,500) to create the window from the previous
paragraph, whatever the resolution of the display is, you would have to
increase this to (1000,1000) on MSW when working on a 200% display. To hide
this difference from the application, wxWidgets provides **device-independent
pixels**, abbreviated as "DIP", that are always of the same size on all
displays and all platforms.
Thus, the first thing do when preparing your application for high DPI support
is to stop using raw pixel values. Actually, using any pixel values is not
recommended and replacing them with the values based on the text metrics, i.e.
obtained using wxWindow::GetTextExtent(), or expressing them in dialog units
(see wxWindow::ConvertDialogToPixels()) is preferable. However the simplest
change is to just replace the pixel values with the values in DIP: for this,
just use wxWindow::FromDIP() to convert from one to the other.
For example, if you have the existing code:
```cpp
myFrame->SetClientSize(wxSize(400, 300));
```
you can just replace it with
```cpp
myFrame->SetClientSize(myFrame->FromDIP(wxSize(400, 300)));
```
Physical Pixels
---------------
In addition to (logical) pixels and DIPs discussed above, you may also need to
work in physical pixel coordinates, corresponding to the actual display pixels.
Physical pixels are never scaled, on any platform, and must be used when
drawing graphics elements to ensure that the best possible resolution is used.
For example, all operations on wxGLCanvas use physical pixels.
To convert between logical and physical pixels, you can use
wxWindow::GetContentScaleFactor(): this is a value greater than or equal to 1,
so a value in logical pixels needs to be multiplied by it in order to obtain
the value in physical pixels.
For example, in a wxGLCanvas created with the size of 100 (logical) pixels, the
rightmost physical pixel coordinate will be `100*GetContentScaleFactor()`.
High-Resolution Images and Artwork
==================================
In order to benefit from the increased detail on High DPI devices you might want
to provide the images or artwork your application uses in higher resolutions as
well. Note that it is not recommended to just provide a high-resolution version
and let the system scale that down on 1x displays. Apart from performance
consideration also the quality might suffer, contours become more blurry.
You can use vector based graphics like SVG or you can add the same image at different
sizes / resolutions.
[comment]: # (TODO: API and Use Cases)
Platform-Specific Build Issues
==============================
Generally speaking, all systems handle applications not specifically marked as
being "DPI-aware" by emulating low-resolution display for them and scaling them
up, resulting in blurry graphics and fonts, but globally preserving the
application appearance. For the best results, the application needs to be
explicitly marked as DPI-aware in a platform-dependent way.
MSW
---
The behaviour of the application when running on a high-DPI display depends on
the values in its [manifest][1]. If your application include `wx/msw/wx.rc`
from its resource file, you need to predefine `wxUSE_DPI_AWARE_MANIFEST` to
opt-in into [high DPI support][2]: define it as `1` for minimal DPI awareness and
`2` for full, per-monitor DPI awareness supported by Windows 10 version 1703 or
later.
[1]: https://docs.microsoft.com/en-us/windows/win32/sbscs/application-manifests
[2]: https://docs.microsoft.com/en-us/windows/win32/hidpi/high-dpi-desktop-application-development-on-windows
macOS
-----
DPI-aware applications must set their `NSPrincipalClass` to `wxNSApplication`
(or at least `NSApplication`) in their `Info.plist` file. Also see Apple [high
resolution guidelines][2] for more information.
[2]: https://developer.apple.com/library/archive/documentation/GraphicsAnimation/Conceptual/HighResolutionOSX/Explained/Explained.html

2
docs/doxygen/overviews/html.h
View File

@@ -13,7 +13,7 @@
The wxHTML library provides classes for parsing and displaying HTML.
It is not intended to be a high-end HTML browser. If you are looking for
something like that try <http://www.mozilla.org/>.
something like that use wxWebView.
wxHTML can be used as a generic rich text viewer - for example to display
a nice About Box (like those of GNOME apps) or to display the result of

11
docs/doxygen/overviews/internationalization.h
View File

@@ -59,6 +59,11 @@ Translating your application involves several steps:
given language: see wxLocale.
@note Under macOS you also need to list all the supported languages under
@c CFBundleLocalizations key in your application @c Info.plist file
in order to allow the application to support the corresponding locale.
@section overview_i18n_mofiles Installing translation catalogs
The .mo files with compiled catalogs must be included with the application.
@@ -75,12 +80,12 @@ locations when possible.
Depending on the platform, the default location differs. On Windows, it is
alongside the executable. On Unix, translations are expected to be in
"$prefix/share/locale". On OS X, application bundle's @em Resources subdirectory
"$prefix/share/locale". On macOS, application bundle's @em Resources subdirectory
is used.
In all cases, translations are searched for in subdirectories named using the
languages codes from ISO 639. The .mo file(s) should be located either directly
in that directory or in LC_MESSAGES subdirectory. On OS X, ".lproj" extension
in that directory or in LC_MESSAGES subdirectory. On macOS, ".lproj" extension
is used for the per-languages Resources subdirectories.
Here's how an app would typically install the files on Unix:
@@ -89,7 +94,7 @@ Here's how an app would typically install the files on Unix:
/usr/share/locale/de/LC_MESSAGES/myapp.mo
/usr/share/locale/fr/LC_MESSAGES/myapp.mo
@endcode
And on OS X:
And on macOS:
@code
MyApp.app/Contents/MacOS/MyApp
MyApp.app/Contents/Resources/de.lproj/myapp.mo

12
docs/doxygen/overviews/log.h
View File

@@ -19,9 +19,9 @@ as well as several standard implementations of it and a family of functions to
use with them.
First of all, no knowledge of wxLog classes is needed to use them. For this,
you should only know about @ref group_funcmacro_log "wxLogXXX() functions".
All of them have the same syntax as @e printf() or @e vprintf() , i.e. they
take the format string as the first argument and respectively a variable number
you should only know about @ref group_funcmacro_log "wxLogXXX() functions".
All of them have the same syntax as @e printf() or @e vprintf() , i.e. they
take the format string as the first argument and respectively a variable number
of arguments or a variable argument list pointer. Here are all of them:
@li wxLogFatalError() which is like wxLogError(), but also terminates the program
@@ -161,8 +161,8 @@ works.
wxWidgets has the notion of a <em>log target</em>: it is just a class deriving
from wxLog. As such, it implements the virtual functions of the base class
which are called when a message is logged. Only one log target is @e active at
any moment, this is the one used by @ref group_funcmacro_log "wxLogXXX() functions".
The normal usage of a log object (i.e. object of a class derived from wxLog) is
any moment, this is the one used by @ref group_funcmacro_log "wxLogXXX() functions".
The normal usage of a log object (i.e. object of a class derived from wxLog) is
to install it as the active target with a call to @e SetActiveTarget() and it
will be used automatically by all subsequent calls to
@ref group_funcmacro_log "wxLogXXX() functions".
@@ -263,7 +263,7 @@ GUI is (already/still) available when your log target as used as wxWidgets
automatically switches to using wxLogStderr if it isn't.
There are several methods which may be overridden in the derived class to
customize log messages handling: wxLog::DoLogRecord(), wxLog::DoLogTextAtLevel()
customize log messages handling: wxLog::DoLogRecord(), wxLog::DoLogTextAtLevel()
and wxLog::DoLogText().
The last method is the simplest one: you should override it if you simply

2
docs/doxygen/overviews/printing.h
View File

@@ -84,7 +84,7 @@ The scaling of the drawn image typically differs from the screen to the preview
and printed images. This class provides a set of routines named
FitThisSizeToXXX(), MapScreenSizeToXXX(), and GetLogicalXXXRect, which can be
used to set the user scale and origin of the wxPrintout's DC so that your class
can easily map your image to the printout withough getting into the details of
can easily map your image to the printout without getting into the details of
screen and printer PPI and scaling. See the printing sample for examples of how
these routines are used.

11
docs/doxygen/overviews/propgrid.h
View File

@@ -733,10 +733,10 @@ accomplish the task:
@code
// Have property editor focus on Enter
propgrid->AddActionTrigger( wxPG_ACTION_EDIT, WXK_RETURN );
// Have Enter work as action trigger even when editor is focused
propgrid->DedicateKey( WXK_RETURN );
// Let Enter also navigate to the next property
propgrid->AddActionTrigger( wxPG_ACTION_NEXT_PROPERTY, WXK_RETURN );
@@ -807,10 +807,9 @@ See wxPGMultiButton class reference.
@subsection propgrid_customeventhandling Handling Events Passed from Properties
<b>wxEVT_COMMAND_BUTTON_CLICKED </b>(corresponds to event table macro EVT_BUTTON):
Occurs when editor button click is not handled by the property itself
(as is the case, for example, if you set property's editor to TextCtrlAndButton
from the original TextCtrl).
@c wxEVT_BUTTON: Occurs when editor button click is not handled by the property
itself (as is the case, for example, if you set property's editor
to TextCtrlAndButton from the original TextCtrl).
@subsection propgrid_attributes Property Attributes

6
docs/doxygen/overviews/richtextctrl.h
View File

@@ -42,7 +42,7 @@ list styles with a renumber option.
There are a few disadvantages to using wxRichTextCtrl. It is not native, so
does not behave exactly as a native wxTextCtrl, although common editing
conventions are followed. Users may miss the built-in spelling correction on
OS X, or any special character input that may be provided by the native
macOS, or any special character input that may be provided by the native
control. It would also be a poor choice if intended users rely on screen
readers that would be not work well with non-native text input implementation.
You might mitigate this by providing the choice between wxTextCtrl and
@@ -415,7 +415,7 @@ set the focus back to the top-level object.
An event will be sent to the control when the focus changes.
When the user clicks on the control, wxRichTextCtrl determines which container
to set as the current object focus by calling the found container's overrided
to set as the current object focus by calling the found container's overridden
wxRichTextObject::AcceptsFocus function. For example, although a table is a
container, it must not itself be the object focus because there is no text
editing at the table level. Instead, a cell within the table must accept the
@@ -495,7 +495,7 @@ tables, text boxes, and floating images, in addition to a simplified-HTML mode f
There are also things that could be done to take advantage of the underlying
text capabilities of the platform; higher-level text formatting APIs are
available on some platforms, such as OS X, and some of translation from
available on some platforms, such as macOS, and some of translation from
high level to low level wxDC API is unnecessary. However this would require
additions to the wxWidgets API.

51
docs/doxygen/overviews/roughguide.h
View File

@@ -11,28 +11,40 @@
@tableofcontents
To set a wxWidgets application going, you will need to derive a wxApp class and
override wxApp::OnInit.
@section overview_roughguide_structure Application Structure
An application must have a top-level wxFrame or wxDialog window. Each frame may
contain one or more instances of classes such as wxPanel, wxSplitterWindow or
other windows and controls.
To set a wxWidgets application going, you will need to derive a wxApp class and
override wxApp::OnInit() in which you will typically create your application
main top-level window.
This window can be a wxFrame or a wxDialog and may contain one or more
instances of classes such as wxPanel, wxSplitterWindow or other windows and
controls. These windows can be created from C++ code or loaded from resource
definitions in @ref overview_xrc "XRC format".
A frame can have a wxMenuBar, a wxToolBar, a wxStatusBar, and a wxIcon for when
the frame is iconized.
A wxPanel is used to place controls (classes derived from wxControl) which are
used for user interaction. Examples of controls are wxButton, wxCheckBox,
wxChoice, wxListBox, wxRadioBox, and wxSlider.
wxChoice, wxListBox, wxRadioBox, and wxSlider. Such controls need to be
positioned correctly -- and also repositioned when the top-level window is
resized by the user -- and to do this you use wxSizer-derived classes, such as
wxBoxSizer and wxFlexGridSizer, to layout everything correctly.
Instances of wxDialog can also be used for controls and they have the advantage
of not requiring a separate frame.
of not requiring a separate panel inside them.
Instead of creating a dialog box and populating it with items, it is possible
to choose one of the convenient common dialog classes, such as wxMessageDialog
and wxFileDialog.
You never draw directly onto a window - you use a <em>device context</em> (DC).
@section overview_roughguide_draw Drawing on the Screen
You never draw directly onto a window -- you use either one of the older
<em>device context</em> (DC) classes or the newer <em>graphics context</em>
(GC) one, that support features such as alpha transparency or anti-aliasing.
wxDC is the base for wxClientDC, wxPaintDC, wxMemoryDC, wxPostScriptDC,
wxMemoryDC, wxMetafileDC and wxPrinterDC. If your drawing functions have wxDC
as a parameter, you can pass any of these DCs to the function, and thus use the
@@ -40,20 +52,19 @@ same code to draw to several different devices. You can draw using the member
functions of wxDC, such as wxDC::DrawLine and wxDC::DrawText. Control colour on
a window (wxColour) with brushes (wxBrush) and pens (wxPen).
To intercept events, you add a wxDECLARE_EVENT_TABLE macro to the window class
declaration, and put a wxBEGIN_EVENT_TABLE ... wxEND_EVENT_TABLE block in the
implementation file. Between these macros, you add event macros which map the
event (such as a mouse click) to a member function. These might override
predefined event handlers such as for wxKeyEvent and wxMouseEvent.
With wxGraphicsContext, you create it using one of the methods of
wxGraphicsRenderer and then construct your drawing from wxGraphicsPath objects,
finally using wxGraphicsContext::StrokePath() or wxGraphicsContext::FillPath().
Most modern applications will have an on-line, hypertext help system; for this,
you need wxHelp and the wxHelpController class to control wxHelp.
GUI applications aren't all graphical wizardry. List and hash table needs are
catered for by wxList and wxHashMap. You will undoubtedly need some
platform-independent @ref group_funcmacro_file, and you may find it handy to
maintain and search a list of paths using wxPathList. There's many
@ref group_funcmacro_misc of operating system methods and other functions.
@section overview_roughguide_events Event Handling
GUI programs spend most of their time waiting for the user-initiated events --
and then processing them. To do it, you use wxEvtHandler::Bind() to specify the
handler for an event of the given time. Event handlers receive the object
describing the event, such as wxKeyEvent or wxMouseEvent, and perform whichever
action corresponds to it. See @ref overview_events "events handling" overview
for much more information about this subject.
@see @ref group_class

20
docs/doxygen/overviews/sizer.h
View File

@@ -15,7 +15,7 @@ Sizers, as represented by the wxSizer class and its descendants in the
wxWidgets class hierarchy, have become the method of choice to define the
layout of controls in dialogs in wxWidgets because of their ability to create
visually appealing dialogs independent of the platform, taking into account
the differences in size and style of the individual controls.
the differences in size and style of the individual controls.
The next section describes and shows what can be done with sizers. The
following sections briefly describe how to program with individual sizer
@@ -211,7 +211,7 @@ window will preserve it is original size, @c wxGROW flag (same as @c wxEXPAND) f
the window to grow with the sizer, and @c wxSHAPED flag tells the window to change
it is size proportionally, preserving original aspect ratio. When @c wxGROW flag
is not used, the item can be aligned within available space. @c wxALIGN_LEFT,
@c wxALIGN_TOP, @c wxALIGN_RIGHT, @c wxALIGN_BOTTOM, @c wxALIGN_CENTER_HORIZONTAL
@c wxALIGN_TOP, @c wxALIGN_RIGHT, @c wxALIGN_BOTTOM, @c wxALIGN_CENTER_HORIZONTAL
and @c wxALIGN_CENTER_VERTICAL do what they say. @c wxALIGN_CENTRE (same as
@c wxALIGN_CENTER) is defined as (<tt>wxALIGN_CENTER_HORIZONTAL | wxALIGN_CENTER_VERTICAL</tt>).
Default alignment is <tt>wxALIGN_LEFT | wxALIGN_TOP</tt>.
@@ -267,7 +267,7 @@ MyDialog::MyDialog(wxFrame *parent, wxWindowID id, const wxString &title )
}
@endcode
Note that the recommended way of specifying flags to wxSizer is via wxSizerFlags.
Note that the recommended way of specifying flags to wxSizer is via wxSizerFlags.
This class greatly eases the burden of passing flags to a wxSizer.
Here's how you'd do the previous example with wxSizerFlags:
@@ -313,18 +313,18 @@ MyDialog::MyDialog(wxFrame *parent, wxWindowID id, const wxString &title )
@section overview_sizer_types Other Types of Sizers
wxStdDialogButtonSizer is a sizer that creates button layouts in dialogs
which conform to the standard button spacing and ordering defined by
wxStdDialogButtonSizer is a sizer that creates button layouts in dialogs
which conform to the standard button spacing and ordering defined by
the platform or toolkit's user interface guidelines (if such things exist).
As a convenience, wxDialog::CreateButtonSizer() can be used to create this sizer.
wxWrapSizer is a sizer that lays out its items in a single line, like a box
sizer -- as long as there is space available in that direction. Once all available
space in the primary direction has been used, a new line is added and items
are added there.
wxWrapSizer is a sizer that lays out its items in a single line, like a box
sizer -- as long as there is space available in that direction. Once all available
space in the primary direction has been used, a new line is added and items
are added there.
wxGridBagSizer is a rather special kind of sizer which, unlike the other
classes, allows to directly put the elements at the given position in the
sizer.
sizer.
*/

32
docs/doxygen/overviews/string.h
View File

@@ -135,7 +135,7 @@ to buffer overflows. At last, C++ has a standard string class (@c std::string).
why the need for wxString? There are several advantages:
@li <b>Efficiency:</b> Since wxWidgets 3.0 wxString uses @c std::string (in UTF8
mode under Linux, Unix and OS X) or @c std::wstring (in UTF16 mode under Windows)
mode under Linux, Unix and macOS) or @c std::wstring (in UTF16 mode under Windows)
internally by default to store its contents. wxString will therefore inherit the
performance characteristics from @c std::string.
@li <b>Compatibility:</b> This class tries to combine almost full compatibility
@@ -236,12 +236,40 @@ arguments should take <tt>const wxString&</tt> (this makes assignment to the
strings inside the function faster) and all functions returning strings
should return wxString - this makes it safe to return local variables.
Finally note that wxString uses the current locale encoding to convert any C string
Note that wxString uses by default the current locale encoding to convert any C string
literal to Unicode. The same is done for converting to and from @c std::string
and for the return value of c_str().
For this conversion, the @a wxConvLibc class instance is used.
See wxCSConv and wxMBConv.
It is also possible to disable any automatic conversions from C
strings to Unicode. This can be useful when the @a wxConvLibc encoding
is not appropriate for the current software and platform. The macro @c
wxNO_IMPLICIT_WXSTRING_ENCODING disables all implicit conversions, and
forces the code to explicitly indicate the encoding of all C strings.
Finally note that encodings, either implicitly or explicitly selected,
may not be able to represent all the string's characters. The result
in this case is undefined: the string may be empty, or the
unrepresentable characters may be missing or wrong.
@code
wxString s;
// s = "world"; does not compile with wxNO_IMPLICIT_WXSTRING_ENCODING
s = wxString::FromAscii("world"); // Always compiles
s = wxASCII_STR("world"); // shorthand for the above
s = wxString::FromUTF8("world"); // Always compiles
s = wxString("world", wxConvLibc); // Always compiles, explicit encoding
s = wxASCII_STR("Grüße"); // Always compiles but encoding fails
const char *c;
// c = s.c_str(); does not compile with wxNO_IMPLICIT_WXSTRING_ENCODING
// c = s.mb_str(); does not compile with wxNO_IMPLICIT_WXSTRING_ENCODING
c = s.ToAscii(); // Always compiles, encoding may fail
c = s.ToUTF8(); // Always compiles, encoding never fails
c = s.utf8_str(); // Alias for the above
c = s.mb_str(wxConvLibc); // Always compiles, explicit encoding
@endcode
@subsection overview_string_iterating Iterating wxString Characters

2
docs/doxygen/overviews/unicode.h
View File

@@ -182,7 +182,7 @@ aware of the potential problems covered by the following section.
wxWidgets uses the system @c wchar_t in wxString implementation by default
under all systems. Thus, under Microsoft Windows, UCS-2 (simplified version of
UTF-16 without support for surrogate characters) is used as @c wchar_t is 2
bytes on this platform. Under Unix systems, including OS X, UCS-4 (also
bytes on this platform. Under Unix systems, including macOS, UCS-4 (also
known as UTF-32) is used by default, however it is also possible to build
wxWidgets to use UTF-8 internally by passing @c \--enable-utf8 option to
configure.

5
docs/doxygen/overviews/windowsizing.h
View File

@@ -116,4 +116,9 @@ some simple explanations of things.
the constraints algorithm is run. The @c Layout() method is what is called by
the default @c EVT_SIZE handler for container windows.
@li wxTopLevelWindow::Layout(): this overridden version does the same thing as
the base wxWindow::Layout() except, for convenience, it will also resize
the only child of the top-level window to cover its entire client area if
there is no sizer associated with the window. Note that this only happens
if there is exactly one child.
*/

4
docs/doxygen/overviews/xrc.h
View File

@@ -196,10 +196,10 @@ void MyClass::ShowDialog()
if (!wxXmlResource::Get()->LoadDialog(&dlg, NULL, "SimpleDialog"))
return;
XRCCTRL(dlg, "text", wxTextCtrl)->Bind(wxEVT_COMMAND_TEXT_UPDATED,
XRCCTRL(dlg, "text", wxTextCtrl)->Bind(wxEVT_TEXT,
wxTextEventHandler(MyClass::OnTextEntered), this, XRCID("text"));
XRCCTRL(dlg, "clickme_btn", wxButton)->Bind(wxEVT_COMMAND_BUTTON_CLICKED,
XRCCTRL(dlg, "clickme_btn", wxButton)->Bind(wxEVT_BUTTON,
wxCommandEventHandler(MyClass::OnClickme), this, XRCID("clickme_btn"));
dlg.ShowModal();

96
docs/doxygen/overviews/xrc_format.h
View File

@@ -115,7 +115,7 @@ These come in two varieties:
("\<label\>Cancel\</label\>"), but they may use nested subelements too (e.g.
@ref overview_xrcformat_type_font "font property"). A property can only be
listed once in an object's definition.
-# Child objects. Window childs, sizers, sizer items or notebook pages
-# Child objects. Window children, sizers, sizer items or notebook pages
are all examples of child objects. They are represented using nested
@c \<object\> elements and are can be repeated more than once. The specifics
of which object classes are allowed as children are class-specific and
@@ -352,6 +352,9 @@ wxFileSystem URL) of the bitmap to use. For example:
The value is interpreted as path relative to the location of XRC file where the
reference occurs.
Bitmap file paths can include environment variables that are expanded if
wxXRC_USE_ENVVARS was passed to the wxXmlResource constructor.
Alternatively, it is possible to specify the bitmap using wxArtProvider IDs.
In this case, the property element has no textual value (filename) and instead
has the @c stock_id XML attribute that contains stock art ID as accepted by
@@ -389,6 +392,16 @@ Examples:
@endcode
@subsection overview_xrcformat_type_showeffect Show Effect
One of the @ref wxShowEffect values.
Example:
@code
<showeffect>wxSHOW_EFFECT_EXPAND</showeffect>
@endcode
@subsection overview_xrcformat_type_font Font
XRC uses similar, but more flexible, abstract description of fonts to that
@@ -756,6 +769,11 @@ Refer to the section @ref xrc_wxtoolbar for more details.
@hdr3col{property, type, description}
@row3col{default, @ref overview_xrcformat_type_bool,
Should this button be the default button in dialog (default: 0)?}
@row3col{close, @ref overview_xrcformat_type_bool,
If set, this is a special "Close" button using system-defined appearance,
see wxBitmapButton::NewCloseButton(). If this property is set, @c bitmap
and @c style are ignored and shouldn't be used. Available since wxWidgets
3.1.5.}
@row3col{bitmap, @ref overview_xrcformat_type_bitmap,
Bitmap to show on the button (default: none).}
@row3col{selected, @ref overview_xrcformat_type_bitmap,
@@ -944,6 +962,9 @@ The wxCommandLinkButton contains a main title-like @c label and an optional
concatenated into a single string using a new line character between them
(notice that the @c note part can have more new lines in it).
Since wxWidgets 3.1.5 it also supports @c default and @c bitmap properties,
just as @ref xrc_wxbutton wxButton.
@beginTable
@hdr3col{property, type, description}
@row3col{label, @ref overview_xrcformat_type_text,
@@ -951,6 +972,10 @@ concatenated into a single string using a new line character between them
will be made when the button is pressed (default: empty). }
@row3col{note, @ref overview_xrcformat_type_text,
Second line of text describing the action performed when the button is pressed (default: none). }
@row3col{bitmap, @ref overview_xrcformat_type_bitmap,
Bitmap to display in the button (optional).}
@row3col{default, @ref overview_xrcformat_type_bool,
Should this button be the default button in dialog (default: 0)?}
@endTable
@@ -1021,6 +1046,25 @@ Example:
@endTable
@subsubsection xrc_wxdataviewctrl wxDataViewCtrl
No additional properties.
@subsubsection xrc_wxdataviewlistctrl wxDataViewListCtrl
No additional properties.
@subsubsection xrc_wxdataviewtreectrl wxDataViewTreeCtrl
@beginTable
@hdr3col{property, type, description}
@row3col{imagelist, @ref overview_xrcformat_type_imagelist,
Image list to use for the images (default: none).}
@endTable
@subsubsection xrc_wxdatepickerctrl wxDatePickerCtrl
No additional properties.
@@ -1153,6 +1197,14 @@ objects. If sizer child is used, it sets
Ignored, preserved only for compatibility.}
@endTable
@subsubsection xrc_wxgenericanimationctrl wxGenericAnimationCtrl
This handler is identical to the one for @ref xrc_wxanimationctrl
"wxAnimationCtrl", please see it for more information. The only difference is
that, for the platforms with a native wxAnimationCtrl implementation, using
this handler creates a generic control rather than a native one.
@subsubsection xrc_wxgenericdirctrl wxGenericDirCtrl
@beginTable
@@ -1199,6 +1251,40 @@ page.
@endTable
@subsubsection xrc_wxinfobar wxInfoBar
@beginTable
@hdr3col{property, type, description}
@row3col{showeffect, @ref overview_xrcformat_type_showeffect,
The effect to use when showing the bar (optional).}
@row3col{hideeffect, @ref overview_xrcformat_type_showeffect,
The effect to use when hiding the bar (optional).}
@row3col{effectduration, integer,
The duration of the animation used when showing or hiding the bar
(optional).}
@row3col{button, object,
Add a button to be shown in the info bar (see wxInfoBar::AddButton);
this property is of class "button" has name (can be one of standard
button ID) and has optional label property. If no buttons are added
to the info bar, the default "Close" button will be shown.}
@endTable
Example:
@code
<object class="wxInfoBar">
<effectduration>1000</effectduration>
<showeffect>wxSHOW_EFFECT_EXPAND</showeffect>
<hideeffect>wxSHOW_EFFECT_SLIDE_TO_RIGHT</hideeffect>
<object class="button" name="wxID_UNDO"/>
<object class="button" name="wxID_REDO">
<label>Redo Custom Label</label>
</object>
</object>
@endcode
@since 3.1.3
@subsubsection xrc_wxlistbox wxListBox
@beginTable
@@ -1745,7 +1831,7 @@ objects have the following properties:
@endTable
A wxRibbonPage may have children of any type derived from wxRibbonControl.
Most commontly, wxRibbonPanel is used. As a special case, the @c panel
Most commonly, wxRibbonPanel is used. As a special case, the @c panel
pseudo-class may be used instead of @c wxRibbonPanel when used as wxRibbonPage
children.
@@ -2589,15 +2675,15 @@ should be processed on. It is filtered out and ignored on any other platforms.
Possible elemental values are:
@beginDefList
@itemdef{ @c win, Windows }
@itemdef{ @c mac, OS X (or Mac Classic in wxWidgets version supporting it) }
@itemdef{ @c unix, Any Unix platform @em except OS X }
@itemdef{ @c mac, macOS (or Mac Classic in wxWidgets version supporting it) }
@itemdef{ @c unix, Any Unix platform @em except macOS }
@endDefList
Examples:
@code
<label platform="win">Windows</label>
<label platform="unix">Unix</label>
<label platform="mac">OS X</label>
<label platform="mac">macOS</label>
<help platform="mac|unix">Not a Windows machine</help>
@endcode