YYCCommonplace/doc/src/win_import.dox

69 lines
2.9 KiB
Plaintext
Raw Normal View History

2024-07-02 16:31:28 +08:00
/**
\page win_import Windows Import Guard
Windows is shitty for the programmer who is familiar with UNIX programming.
Due to legacy reason, Windows defines various things which are not compatible with UNIX or standard C++ programming.
\section win_import__usage Usage
YYCC has a way to solve the issue introduced above.
2024-07-02 16:31:28 +08:00
\code
#if YYCC_OS == YYCC_OS_WINDOWS
2024-07-02 16:31:28 +08:00
#include <WinImportPrefix.hpp>
#include <Windows.h>
#include "other_header_depend_on_windows.h"
#include <WinImportSuffix.hpp>
#endif
2024-07-02 16:31:28 +08:00
\endcode
The including of WinImportPrefix.hpp and WinImportSuffix.hpp is a pair.
They just like a guard bracket the include operation of Windows related headers,
to keep all Windows shitty contents will not be leaked outside.
This guard can solve following issues:
<UL>
<LI>
Programmer can not use \c std::max and \c std::min normally.
<UL>
<LI>Windows defines \c MAX and \c MIN as macros for personal use. This is why this happend.</LI>
<LI>Guard defines some special macros to tell Windows do not create these 2 macros.</LI>
</UL>
</LI>
<LI>
Programmer will not be affected by the automatical rename of \c GetObject, \c GetClassName and etc.
<UL>
<LI>These are all macros for Windows personal use to automatically redirect calling to A function and W function by compiling environment.</LI>
<LI>Guard \c #undef these annoy macros.</LI>
</UL>
</LI>
<LI>
Compiler throw annoy warnings and errors when using specific standard library functions.
<UL>
<LI>MSVC will throw warnings and errors when you are using Microsoft so-called \e depracted or \e unsafe standard library functions.</LI>
<LI>YYCCInternal.hpp, which has been included by this pair, defines some macros to purge these warnings and errors out.</LI>
</UL>
</LI>
</UL>
\section win_import__notes Notes
2024-07-02 16:31:28 +08:00
If you have other header files which are strongly depend on Windows header,
you should put them into this bracket at the same time like example did.
Because this guard operate some Windows macros as we introduced above.
The headers depending on Windows may throw error if you put them outside of this pair.
Please note WinImportPrefix.hpp and WinImportSuffix.hpp can be included multiple times.
Because they do not have the proprocessor command like <I>#pragma once</I> or etc to make sure they only can be included once.
That's by design. Because we actually may use this pair multiple times.
The only thing you should pledge is that you must make sure they are presented by pair.
This guard is Windows specific.
It does nothing if you accidently use it in other platforms such as Linux,
because the headers use \c #if to check environment out and will do nothing in non-Windows environment.
However, we still highly recommend you use this pair with platform checker bracket like example does,
if your program need to be run on multiple platforms.
2024-07-02 16:31:28 +08:00
*/