PCSX2 Documentation/WxWidgets Coding Strategies: Difference between revisions
PCSX2 Documentation/WxWidgets Coding Strategies (view source)
Revision as of 18:09, 25 June 2024
, 25 JuneUpdate.
No edit summary |
(Update.) |
||
(5 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
<center>{{Warning|<big>'''This guide is outdated as PCSX2 now uses Qt!'''<br/>Please refer to the PCSX2 Discord server if you wish to help with programming.</big>}}</center> | |||
==Guidelines== | ==Guidelines== | ||
The wx-based codebase for PCSX2 is designed to 'lean' heavily on wxWidgets, meaning that PCSX2 will whenever possible use wx-provided tools and classes instead of re-inventing our own. This decision was made as it allows us take full advantage of the cross-platform tools offered by wxWidgets, which ensures more correct behavior on Windows and Linux alike and, in turn makes life simpler for all PCSX2 developers. | The wx-based codebase for PCSX2 is designed to 'lean' heavily on wxWidgets, meaning that PCSX2 will whenever possible use wx-provided tools and classes instead of re-inventing our own. This decision was made as it allows us take full advantage of the cross-platform tools offered by wxWidgets, which ensures more correct behavior on Windows and Linux alike and, in turn makes life simpler for all PCSX2 developers. | ||
Line 60: | Line 61: | ||
There are several ways to send events between windows in wxWidgets, and only one of them is typically the ''correct'' way: | There are several ways to send events between windows in wxWidgets, and only one of them is typically the ''correct'' way: | ||
<source lang="cpp"> | |||
// This method ensures cross-platform consistency and thread safety, but cannot be | |||
// used to get a return code. | |||
myWidget->GetEventHandler()->AddPendingEvent( evt ); | |||
// This one performs an immediate handling of the event, and should only be used | |||
// if you need a return code, or know for sure the caller is on the Main/GUI thread | |||
myWidget->GetEventHandler()->ProcessEvent( evt ); | |||
// The wxApp class does not have a GetEventHandler() so for it you use this: | |||
wxGetApp()->AddPendingEvent( evt ); // safe from any thread | |||
wxGetApp()->ProcessEvent( evt ); // safe form GUI thread only | |||
</source> | |||
This can be a bit confusing because wx has several other options for sending events, and most of them have caveats as noted below: | This can be a bit confusing because wx has several other options for sending events, and most of them have caveats as noted below: | ||
<source lang="cpp"> | |||
//This one works but is depreciated, and can lead to cross-platform inconsistencies: | |||
myWidget->AddPendingEvent( evt ); | |||
//This one has the same problem as above. | |||
wxPostEvent( myWidget, evt ); | |||
// This one actually works correctly, but might as well just use the more direct | |||
// example of myWidget->GetEventHandler()->AddPendingEvent( evt ); | |||
wxPostEvent( myWidget->GetEventHandler(), evt ); | |||
</source> | |||
... So the moral of the story is: Use <code>GetEventHandler()</code> when possible (basically anything except the <code>wxApp</code> object), and use <code lang="cpp">AddPendingEvent()</code> unless you need a return code ''and'' know you're on the main GUI thread. | |||
... So the moral of the story is: Use <code>GetEventHandler()</code> when possible (basically anything except the <code>wxApp</code> object), and use <code>AddPendingEvent()</code> unless you need a return code ''and'' know you're on the main GUI thread. | |||
==Guidelines when Using Windows/Linux Specific Code== | ==Guidelines when Using Windows/Linux Specific Code== | ||
Line 97: | Line 101: | ||
As noted, it's generally preferred to create implementations in platform specific files over using <code>#ifdef</code>. This helps keep code much cleaner and saner, and is more friendly toward code editors/IDEs as well (most editors handle <code>#ifdef</code> poorly, either failing to gray out the unused defines, or by enforcing an ugly tabbing layout that is only suited to function-level codeblock removal). When using platform specific files it's usually preferred to have each filename assigned the platform's tag. Example: | As noted, it's generally preferred to create implementations in platform specific files over using <code>#ifdef</code>. This helps keep code much cleaner and saner, and is more friendly toward code editors/IDEs as well (most editors handle <code>#ifdef</code> poorly, either failing to gray out the unused defines, or by enforcing an ugly tabbing layout that is only suited to function-level codeblock removal). When using platform specific files it's usually preferred to have each filename assigned the platform's tag. Example: | ||
<source lang="bash"> | |||
/Windows/WinSpecific.cpp | |||
/Linux/LnxSpecific.cpp | |||
</source> | |||
... as this provides a clear identifier to cross-platform programmers which files they're looking at when they use things like Find-in-Files and other global search tools. | ... as this provides a clear identifier to cross-platform programmers which files they're looking at when they use things like Find-in-Files and other global search tools. | ||
{{PCSX2 Documentation Navbox}} | {{PCSX2 Documentation Navbox}} |