PCSX2 Documentation/WxWidgets Coding Strategies: Difference between revisions

This means that you should, whenever possible, use the following classes instead of other common alternatives:

'''There are some exceptions to this last rule:'''

(any others...?)

PCSX2 opts for the "hand-made" approach to dialog box design, rather than using form designers and resource files. This reduces the number of external library and application dependencies needed to build or contribute to PCSX2, and is often an ideal approach to GUI design via sizers and spacers (which is the preferred layout system in wxwidgets). Make sure to always create a new dialog/UI as one or more **Panels**, rather than adding controls directly to a Dialog window. Panels are much more flexable devices and they allow us the option of adding dockable panel features to PCSX2's UI at a later date. Panels also make re-arranging the window contents of the current static GUI a lot easier (if necessary).

... If using native wxWidgets controls with tooltips, use `pxSetToolTip` instead of the control's built in `SetToolTip.` This ensures proper tooltip length on win32 platforms. Custom px-based controls override the SetToolTip internally to do word wrapping as needed, so you can use their built-in `SetToolTip` methods.

The primary purpose of wxPanelWithHelpers is to compensate for wxWidgets inability to resize panels and dialogs with static text word wrapping in mind. (****see below for details on why) So instead we specify the ideal or maximum width of the dialog to wxPanelWithHelpers, and then use our own `pxStaticText` widget to add wrappable text to the panel, which will be wrapped to fit to the ideal width of the panel. Child panels of the wxPanelWithHelpers automatically inherit the maximum width from that panel, and automatically guesstimate their own width based on typical borders offrames and static group boxes.

TODO: In the future it might work best to have the ideal/maximum width be a function of the user's dialog font size, to allow for the dialog to expand to accomodte the real-estire of larger fonts.

As of the writing of this doc, this topic is still a work-in-progress on the wx branch, meaning that there are still a few spots in the Emulation Core code that make direct references to the gui. These spots willhopefully get resolved in the near future.

Currently however there is no distinct separation between the emulation core and the wx-based GUI, since there are still several intertwined dependencies that still need to be dealt with in a nice manner.

The emulator core and UI are now running on independent threads, which means the UI cannot safely change the emulator's settings whenever it feels like it. This will result in nasty bugs caused by obscure threading race conditions. To solve this, most Core and UI settings have been separated into two structures, `Pcsx2Config` (for core emu options), and `AppConfig` (wx-UI options). `AppConfig` contains its own copy of `Pcsx2Config` since, as a UI, it needs to maintain both its own options and the options it uses to invoke emulation. The wxUI's instance of AppConfig is called `g_Conf`. The emu core uses its own local copy of settings, called `EmuConfig`, (defined as `extern const Pcsx2Config EmuConfig`).

There are several other guidelines you need to be aware of before attempting to modify PCSX2 settings. Please read Settings between UI and Core Threads for more details on how to use the two-conf system.

_TODO : obsolete. Replace with a link to documented use of th new pxEvent system._

... So the moral of the story is: Use `GetEventHandler()` when possible (basically anything except the `wxApp` object), and use `AddPendingEvent()` unless you need a return code _and_ know you're on the main GUI thread.

The simple rule is to not use any windows or linux specific code unless absolutely necessary. Most of the time _wxWidgets_ provisions us with cross-platform alternatives for most tasks, so always make sure to check the wx documentation first. But, of course, there are still cases of advanced coding that wx doesn't cover, and these will need platform specific implementations. For example, there is no direct Linux equivalent of Windows Structured Exception Handling (SEH), and PCSX2 code that uses SEH must either be coded to use Linux signals (if possible) or `#ifdef`'d out under Linux.

As noted, it's generally preferred to create implementations in platform specific files over using `#ifdef`. This helps keep code much cleaner and saner, and is more friendly toward code editors/IDEs as well (most editors handle `#ifdef` 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: