diff --git a/Doxyfile.in b/Doxyfile.in index aea63faecd..38aa129ca2 100644 --- a/Doxyfile.in +++ b/Doxyfile.in @@ -45,7 +45,7 @@ PYTHON_DOCSTRING = YES INHERIT_DOCS = YES SEPARATE_MEMBER_PAGES = NO TAB_SIZE = 2 -ALIASES = +ALIASES = important="@attention" # @important is available in newer versions of doxygen. OPTIMIZE_OUTPUT_FOR_C = YES OPTIMIZE_OUTPUT_JAVA = NO OPTIMIZE_FOR_FORTRAN = NO @@ -134,7 +134,9 @@ FILE_PATTERNS = *.c \ *.cpp \ *.c++ \ *.h \ - *.hpp + *.hpp \ + *.mm \ + *.m RECURSIVE = YES EXCLUDE = EXCLUDE_SYMLINKS = NO @@ -317,6 +319,7 @@ PREDEFINED = WITH_ZLIB \ WITH_HARFBUZZ \ WITH_ICU_I18N \ UNICODE \ + DOXYGEN_API \ _UNICODE \ _GNU_SOURCE \ FINAL= diff --git a/src/os/macosx/CMakeLists.txt b/src/os/macosx/CMakeLists.txt index a494825b49..8a1db47e3f 100644 --- a/src/os/macosx/CMakeLists.txt +++ b/src/os/macosx/CMakeLists.txt @@ -4,6 +4,7 @@ add_files( font_osx.h macos.h macos.mm + macos_objective_c.h osx_stdafx.h string_osx.cpp string_osx.h diff --git a/src/os/macosx/macos.mm b/src/os/macosx/macos.mm index 9aaa2de340..ee209917b6 100644 --- a/src/os/macosx/macos.mm +++ b/src/os/macosx/macos.mm @@ -5,7 +5,12 @@ * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see . */ -/** @file macos.mm Code related to MacOSX. */ +/** + * @file macos.mm Code related to MacOSX. + * + * This file contains objective C. + * Apple uses objective C instead of plain C to interact with OS specific/native functions. + */ #include "../../stdafx.h" #include "../../core/bitmath_func.hpp" @@ -14,18 +19,7 @@ #include "../../string_func.h" #include "../../fileio_func.h" #include - -#define Rect OTTDRect -#define Point OTTDPoint -#include -#undef Rect -#undef Point - -/* - * This file contains objective C - * Apple uses objective C instead of plain C to interact with OS specific/native functions - */ - +#include "macos_objective_c.h" #ifdef WITH_COCOA static NSAutoreleasePool *_ottd_autorelease_pool; @@ -58,44 +52,28 @@ void GetMacOSVersion(int *return_major, int *return_minor, int *return_bugfix) } #ifdef WITH_COCOA - extern void CocoaDialog(std::string_view title, std::string_view message, std::string_view buttonLabel); - -/** - * Show the system dialogue message (Cocoa on MacOSX). - * - * @param title Window title. - * @param message Message text. - * @param buttonLabel Button text. - */ -void ShowMacDialog(std::string_view title, std::string_view message, std::string_view buttonLabel) -{ - CocoaDialog(title, message, buttonLabel); -} - - -#else - -/** - * Show the system dialogue message (console on MacOSX). - * - * @param title Window title. - * @param message Message text. - * @param buttonLabel Button text. - */ -void ShowMacDialog(std::string_view title, std::string_view message, std::string_view buttonLabel) -{ - fmt::print(stderr, "{}: {}\n", title, message); -} - #endif +/** + * Show the system dialogue message, uses Cocoa if available and console otherwise. + * @param title Window title. + * @param message Message text. + * @param buttonLabel Button text. + */ +void ShowMacDialog(std::string_view title, std::string_view message, std::string_view buttonLabel) +{ +#ifdef WITH_COCOA + CocoaDialog(title, message, buttonLabel); +#else + fmt::print(stderr, "{}: {}\n", title, message); +#endif +} /** * Show an error message. - * - * @param buf error message text. - * @param system message text originates from OS. + * @param buf Text with error message. + * @param system Whether message text originates from OS. */ void ShowOSErrorBox(std::string_view buf, bool system) { @@ -107,13 +85,18 @@ void ShowOSErrorBox(std::string_view buf, bool system) } } +/** + * Opens browser on MacOS. + * @param url Web page address to open. + */ void OSOpenBrowser(const std::string &url) { [ [ NSWorkspace sharedWorkspace ] openURL:[ NSURL URLWithString:[ NSString stringWithUTF8String:url.c_str() ] ] ]; } /** - * Determine and return the current user's locale. + * Determine and return the current user's charset. + * @return String containing current charset, or std::nullopt if not-determinable. */ std::optional GetCurrentLocale(const char *) { @@ -220,6 +203,10 @@ void MacOSSetThreadName(const std::string &name) } } +/** + * Ask OS how much RAM it has physically attached. + * @return Number of available bytes. + */ uint64_t MacOSGetPhysicalMemory() { return [ [ NSProcessInfo processInfo ] physicalMemory ]; diff --git a/src/os/macosx/macos_objective_c.h b/src/os/macosx/macos_objective_c.h new file mode 100644 index 0000000000..422e3b88b8 --- /dev/null +++ b/src/os/macosx/macos_objective_c.h @@ -0,0 +1,28 @@ +/* + * This file is part of OpenTTD. + * OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2. + * OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see . + */ + +/** @file macos_objective_c.h Includes of mac os specific headers wich contain objective c. */ + +#ifndef MACOS_OBJECTIVE_C_H +#define MACOS_OBJECTIVE_C_H + +/** Macro that prevents name conflicts between included headers. */ +#define Rect OTTDRect +/** Macro that prevents name conflicts between included headers. */ +#define Point OTTDPoint +#include + +#ifdef WITH_COCOA +#import +#import +#endif /* WITH_COCOA */ + +#undef Rect +#undef Point + +#endif /* MACOS_OBJECTIVE_C_H */ + diff --git a/src/video/cocoa/cocoa_ogl.mm b/src/video/cocoa/cocoa_ogl.mm index 8c52ee0cfb..8fd62478c2 100644 --- a/src/video/cocoa/cocoa_ogl.mm +++ b/src/video/cocoa/cocoa_ogl.mm @@ -5,22 +5,25 @@ * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see . */ -/** @file cocoa_ogl.mm Code related to the cocoa OpengL video driver. */ +/** + * @file cocoa_ogl.mm Code related to the cocoa OpengL video driver. + * + * @important Notice regarding all modifications!!!!!!! + * There are certain limitations because the file is objective C++. + * gdb has limitations. + * C++ and objective C code can't be joined in all cases (classes stuff). + * Read http://developer.apple.com/releasenotes/Cocoa/Objective-C++.html for more information. + */ -#ifdef WITH_COCOA +#if defined(WITH_COCOA) || defined(DOXYGEN_API) #include "../../stdafx.h" #include "../../os/macosx/macos.h" +/** Macro defined before OpenGL and GLUT includes to avoid deprecation messages. */ #define GL_SILENCE_DEPRECATION -#define Rect OTTDRect -#define Point OTTDPoint -#import -#import -#undef Rect -#undef Point - +#include "../../os/macosx/macos_objective_c.h" #include "../../openttd.h" #include "../../debug.h" #include "../../core/geometry_func.hpp" @@ -38,15 +41,6 @@ static Palette _local_palette; ///< Current palette to use for drawing. - -/** - * Important notice regarding all modifications!!!!!!! - * There are certain limitations because the file is objective C++. - * gdb has limitations. - * C++ and objective C code can't be joined in all cases (classes stuff). - * Read http://developer.apple.com/releasenotes/Cocoa/Objective-C++.html for more information. - */ - /** Platform-specific callback to get an OpenGL function pointer. */ static OGLProc GetOGLProcAddressCallback(const char *proc) { @@ -181,6 +175,7 @@ static bool _allowSoftware; @end +/** Storage for instance of the FVideoDriver_CocoaOpenGL class. */ static FVideoDriver_CocoaOpenGL iFVideoDriver_CocoaOpenGL; @@ -330,4 +325,4 @@ void VideoDriver_CocoaOpenGL::Paint() [ CATransaction commit ]; } -#endif /* WITH_COCOA */ +#endif /* WITH_COCOA or DOXYGEN_API */ diff --git a/src/video/cocoa/cocoa_v.mm b/src/video/cocoa/cocoa_v.mm index a513243c22..bb9bb7f101 100644 --- a/src/video/cocoa/cocoa_v.mm +++ b/src/video/cocoa/cocoa_v.mm @@ -5,26 +5,22 @@ * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see . */ -/** @file cocoa_v.mm Code related to the cocoa video driver(s). */ +/** + * @file cocoa_v.mm Code related to the cocoa video driver(s). + * + * @important Notice regarding all modifications!!!!!!! + * There are certain limitations because the file is objective C++. + * gdb has limitations. + * C++ and objective C code can't be joined in all cases (classes stuff). + * Read http://developer.apple.com/releasenotes/Cocoa/Objective-C++.html for more information. + */ -/****************************************************************************** - * Cocoa video driver * - * Known things left to do: * - * Nothing at the moment. * - ******************************************************************************/ - -#ifdef WITH_COCOA +#if defined(WITH_COCOA) || defined(DOXYGEN_API) #include "../../stdafx.h" #include "../../os/macosx/macos.h" -#define Rect OTTDRect -#define Point OTTDPoint -#import -#import -#undef Rect -#undef Point - +#include "../../os/macosx/macos_objective_c.h" #include "../../openttd.h" #include "../../debug.h" #include "../../error_func.h" @@ -45,18 +41,9 @@ #import /* for MAXPATHLEN */ #import /* gettimeofday */ -/** - * Important notice regarding all modifications!!!!!!! - * There are certain limitations because the file is objective C++. - * gdb has limitations. - * C++ and objective C code can't be joined in all cases (classes stuff). - * Read http://developer.apple.com/releasenotes/Cocoa/Objective-C++.html for more information. - */ - -bool _cocoa_video_started = false; +bool _cocoa_video_started = false; ///< Is the Cocoa video driver running. static Palette _local_palette; ///< Current palette to use for drawing. - -extern bool _tab_is_down; +extern bool _tab_is_down; ///< Is tab button pressed. /** List of common display/window sizes. */ @@ -110,7 +97,10 @@ void VideoDriver_Cocoa::Stop() _cocoa_video_started = false; } -/** Common driver initialization. */ +/** + * Common driver initialization. + * @return Error message if one has occurred, std::nullopt otherwise. + */ std::optional VideoDriver_Cocoa::Initialize() { if (!MacOSVersionIsAtLeast(10, 7, 0)) return "The Cocoa video driver requires Mac OS X 10.7 or later."; @@ -241,6 +231,7 @@ void VideoDriver_Cocoa::EditBoxLostFocus() /** * Get refresh rates of all connected monitors. + * @return Refresh rates of all connected monitors. */ std::vector VideoDriver_Cocoa::GetListOfMonitorRefreshRates() { @@ -265,6 +256,7 @@ std::vector VideoDriver_Cocoa::GetListOfMonitorRefreshRates() /** * Get the resolution of the main screen. + * @return The resolution of the main screen. */ Dimension VideoDriver_Cocoa::GetScreenSize() const { @@ -272,7 +264,10 @@ Dimension VideoDriver_Cocoa::GetScreenSize() const return { static_cast(NSWidth(frame)), static_cast(NSHeight(frame)) }; } -/** Lock video buffer for drawing if it isn't already mapped. */ +/** + * Lock video buffer for drawing if it isn't already mapped. + * @return True on success and false otherwise. + */ bool VideoDriver_Cocoa::LockVideoBuffer() { if (this->buffer_locked) return false; @@ -351,6 +346,7 @@ void VideoDriver_Cocoa::UpdateVideoModes() * Build window and view with a given size. * @param width Window width. * @param height Window height. + * @return True on success and false otherwise. */ bool VideoDriver_Cocoa::MakeWindow(int width, int height) { @@ -480,15 +476,21 @@ void VideoDriver_Cocoa::MainLoopReal() } -/* Subclass of OTTD_CocoaView to fix Quartz rendering */ +/** Subclass of OTTD_CocoaView to fix Quartz rendering */ @interface OTTD_QuartzView : NSView { - VideoDriver_CocoaQuartz *driver; + VideoDriver_CocoaQuartz *driver; ///< The driver to fix rendering for. } - (instancetype)initWithFrame:(NSRect)frameRect andDriver:(VideoDriver_CocoaQuartz *)drv; @end @implementation OTTD_QuartzView +/** + * Construct new instance. + * @param frameRect Size of frame. + * @param drv Driver to fix rendering for. + * @return The newly created instance. + */ - (instancetype)initWithFrame:(NSRect)frameRect andDriver:(VideoDriver_CocoaQuartz *)drv { if (self = [ super initWithFrame:frameRect ]) { @@ -504,21 +506,34 @@ void VideoDriver_Cocoa::MainLoopReal() return self; } +/** + * Specifies whether the view accepts first responder. + * @return Always no. + */ - (BOOL)acceptsFirstResponder { return NO; } +/** + * Specifies whether the view is opaque. + * @return Always yes. + */ - (BOOL)isOpaque { return YES; } +/** + * Specifies whether the view wants updates for layer. + * @return Always yes. + */ - (BOOL)wantsUpdateLayer { return YES; } +/** Updates the layer based on driver data. */ - (void)updateLayer { if (driver->cgcontext == nullptr) return; @@ -529,6 +544,7 @@ void VideoDriver_Cocoa::MainLoopReal() CGImageRelease(fullImage); } +/** Updates members with new values after changes in driver. */ - (void)viewDidChangeBackingProperties { [ super viewDidChangeBackingProperties ]; @@ -538,10 +554,12 @@ void VideoDriver_Cocoa::MainLoopReal() @end - -static FVideoDriver_CocoaQuartz iFVideoDriver_CocoaQuartz; - -/** Clear buffer to opaque black. */ +/** + * Clear buffer to opaque black. + * @param buffer Pointer to the buffer. + * @param pitch Width of the buffer. + * @param height Height of the buffer. + */ static void ClearWindowBuffer(uint32_t *buffer, uint32_t pitch, uint32_t height) { uint32_t fill = Colour(0, 0, 0).data; @@ -609,8 +627,11 @@ NSView *VideoDriver_CocoaQuartz::AllocateDrawView() return [ [ OTTD_QuartzView alloc ] initWithFrame:[ this->cocoaview bounds ] andDriver:this ]; } -/** Resize the window. */ -void VideoDriver_CocoaQuartz::AllocateBackingStore(bool) +/** + * Resize the window. + * @param force If true window resizing will be forced. + */ +void VideoDriver_CocoaQuartz::AllocateBackingStore([[maybe_unused]] bool force) { if (this->window == nil || this->cocoaview == nil || this->setup) return; @@ -684,7 +705,11 @@ void VideoDriver_CocoaQuartz::BlitIndexedToView32(int left, int top, int right, } } -/** Update the palette */ +/** + * Update the palette + * @param first_colour Index of first colour to update. + * @param num_colours How many colours to update, should be greater than 0. + */ void VideoDriver_CocoaQuartz::UpdatePalette(uint first_colour, uint num_colours) { if (this->buffer_depth != 8) return; @@ -756,4 +781,4 @@ void VideoDriver_CocoaQuartz::Paint() this->dirty_rect = {}; } -#endif /* WITH_COCOA */ +#endif /* WITH_COCOA or DOXYGEN_API */ diff --git a/src/video/cocoa/cocoa_wnd.mm b/src/video/cocoa/cocoa_wnd.mm index ec14347c24..5518e182cf 100644 --- a/src/video/cocoa/cocoa_wnd.mm +++ b/src/video/cocoa/cocoa_wnd.mm @@ -5,25 +5,24 @@ * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see . */ -/** @file cocoa_wnd.mm Code related to OS interface for the cocoa video driver. */ +/** + * @file cocoa_wnd.mm Code related to OS interface for the cocoa video driver. + * + * @important Notice regarding all modifications!!!!!!! + * There are certain limitations because the file is objective C++. + * gdb has limitations. + * C++ and objective C code can't be joined in all cases (classes stuff). + * Read http://developer.apple.com/releasenotes/Cocoa/Objective-C++.html for more information. + * + * @todo List available resolutions. + */ -/****************************************************************************** - * Cocoa video driver * - * Known things left to do: * - * List available resolutions. * - ******************************************************************************/ - -#ifdef WITH_COCOA +#if defined(WITH_COCOA) || defined(DOXYGEN_API) #include "../../stdafx.h" #include "../../os/macosx/macos.h" -#define Rect OTTDRect -#define Point OTTDPoint -#import -#undef Rect -#undef Point - +#include "../../os/macosx/macos_objective_c.h" #include "../../openttd.h" #include "../../debug.h" #include "cocoa_v.h" @@ -43,22 +42,18 @@ /* Table data for key mapping. */ #include "cocoa_keys.h" -/** - * Important notice regarding all modifications!!!!!!! - * There are certain limitations because the file is objective C++. - * gdb has limitations. - * C++ and objective C code can't be joined in all cases (classes stuff). - * Read http://developer.apple.com/releasenotes/Cocoa/Objective-C++.html for more information. - */ - +/** Structure to store information about single touch bar button. */ struct TouchBarButton { - NSTouchBarItemIdentifier key; - SpriteID sprite; - MainToolbarHotkeys hotkey; - NSString *fallback_text; + NSTouchBarItemIdentifier key; ///< Unique identifier for this button. + SpriteID sprite; ///< Sprite to display on button. + MainToolbarHotkeys hotkey; ///< Index of widget that corresponds to this button. + NSString *fallback_text; ///< Text to use if sprite is unavailable. }; -/* 9 items can be displayed on the touch bar when using default buttons. */ +/** + * Storage of defined touch bar buttons. + * @note 9 items can be displayed on the touch bar when using default buttons. + */ static const std::array _touchbar_buttons{{ { @"openttd.pause", SPR_IMG_PAUSE, MTHK_PAUSE, @"Pause" }, { @"openttd.fastforward", SPR_IMG_FASTFORWARD, MTHK_FASTFORWARD, @"Fast Forward" }, @@ -71,23 +66,23 @@ static const std::array _touchbar_buttons{{ { @"openttd.build_airport", SPR_IMG_BUILDAIR, MTHK_BUILD_AIRPORT, @"Airport" } }}; -bool _allow_hidpi_window = true; // Referenced from table/misc_settings.ini +bool _allow_hidpi_window = true; ///< Storage for allow_hidpi setting. If true renders OTTD in native resolution. @see table/misc_settings.ini @interface OTTDMain : NSObject @end +/** Name of notification observer used to restart the game loop if necessary. */ NSString *OTTDMainLaunchGameEngine = @"ottdmain_launch_game_engine"; -bool _tab_is_down; +bool _tab_is_down; ///< Is tab button pressed. -static bool _cocoa_video_dialog = false; -static OTTDMain *_ottd_main; +static bool _cocoa_video_dialog = false; ///< True iff inside the scope of CocoaDialog method. +static OTTDMain *_ottd_main; ///< App delegate instance of OTTDMain. /** * Count the number of UTF-16 code points in a range of an UTF-8 string. - * @param from Start of the range. - * @param to End of the range. + * @param str The view in range of the string. * @return Number of UTF-16 code points in the range. */ static NSUInteger CountUtf16Units(std::string_view str) @@ -141,6 +136,10 @@ static std::vector NSStringToUTF32(NSString *s) return unicode_str; } +/** + * Free memory where data was stored. + * @param data Pointer to memory that will be freed. + */ static void CGDataFreeCallback(void *, const void *data, size_t) { delete[] (const uint32_t *)data; @@ -326,6 +325,7 @@ static void setupWindowMenu() /** * Startup the application. + * @return True iff startup was successful. */ bool CocoaSetupApplication() { @@ -376,7 +376,7 @@ void CocoaExitApplication() * @param message Message text. * @param buttonLabel Button text. * - * @note This is needed since sometimes assert is called before the videodriver is initialized . + * @note This is needed since sometimes assert is called before the videodriver is initialized. */ void CocoaDialog(std::string_view title, std::string_view message, std::string_view buttonLabel) { @@ -410,6 +410,10 @@ void CocoaDialog(std::string_view title, std::string_view message, std::string_v * Re-implement the system cursor in order to allow hiding and showing it nicely */ @implementation NSCursor (OTTD_CocoaCursor) +/** + * Create clear cursor for cocoa driver. + * @return The created cursor. + */ + (NSCursor *) clearCocoaCursor { /* RAW 16x16 transparent GIF */ @@ -427,7 +431,7 @@ void CocoaDialog(std::string_view title, std::string_view message, std::string_v @implementation OTTD_CocoaWindow { VideoDriver_Cocoa *driver; - bool touchbar_created; + bool touchbar_created; ///< Whether the touchbar exists. } /** @@ -536,8 +540,8 @@ void CocoaDialog(std::string_view title, std::string_view message, std::string_v @implementation OTTD_CocoaView { float _current_magnification; - NSUInteger _current_mods; - bool _emulated_down; + NSUInteger _current_mods; ///< Currently applied modifier flags. + bool _emulated_down; ///< Whether the mouse button is emulated or real. bool _use_hidpi; ///< Render content in native resolution? } @@ -602,14 +606,16 @@ void CocoaDialog(std::string_view title, std::string_view message, std::string_v [ track release ]; } /** - * Make OpenTTD aware that it has control over the mouse + * Make OpenTTD aware that it has control over the mouse. + * @param theEvent Information about occurred event. */ - (void)mouseEntered:(NSEvent *)theEvent { _cursor.in_window = true; } /** - * Make OpenTTD aware that it has NOT control over the mouse + * Make OpenTTD aware that it has NO control over the mouse. + * @param theEvent Information about occurred event. */ - (void)mouseExited:(NSEvent *)theEvent { @@ -618,9 +624,9 @@ void CocoaDialog(std::string_view title, std::string_view message, std::string_v } /** - * Return the mouse location - * @param event UI event - * @return mouse location as NSPoint + * Return the mouse location. + * @param e Information about occurred event. + * @return Mouse location as NSPoint. */ - (NSPoint)mousePositionFromEvent:(NSEvent *)e { @@ -631,6 +637,10 @@ void CocoaDialog(std::string_view title, std::string_view message, std::string_v return [ self getRealRect:NSMakeRect(pt.x, self.bounds.size.height - pt.y, 0, 0) ].origin; } +/** + * Internal handler of mouse movement. + * @param event Information about occurred event. + */ - (void)internalMouseMoveEvent:(NSEvent *)event { if (_cursor.fix_at) { @@ -643,6 +653,9 @@ void CocoaDialog(std::string_view title, std::string_view message, std::string_v HandleMouseEvents(); } +/** + * Internal handler of mouse buttons. + */ - (void)internalMouseButtonEvent { bool cur_fix = _cursor.fix_at; @@ -652,6 +665,11 @@ void CocoaDialog(std::string_view title, std::string_view message, std::string_v if (cur_fix != _cursor.fix_at) CGAssociateMouseAndMouseCursorPosition(!_cursor.fix_at); } +/** + * Check if right mouse button should be emulated when left button is pressed. + * @param event Information about occurred event. + * @return True iff right button should be emulated instead of left one. + */ - (BOOL)emulateRightButton:(NSEvent *)event { uint32_t keymask = 0; @@ -661,15 +679,28 @@ void CocoaDialog(std::string_view title, std::string_view message, std::string_v return (event.modifierFlags & keymask) != 0; } +/** + * Handler of mouse movement. + * @param event Information about occurred event. + */ - (void)mouseMoved:(NSEvent *)event { [ self internalMouseMoveEvent:event ]; } +/** + * Handler of mouse movement while left button is down. + * @param event Information about occurred event. + */ - (void)mouseDragged:(NSEvent *)event { [ self internalMouseMoveEvent:event ]; } + +/** + * Handler of left mouse button pressing. + * @param event Information about occurred event. + */ - (void)mouseDown:(NSEvent *)event { if ([ self emulateRightButton:event ]) { @@ -680,6 +711,11 @@ void CocoaDialog(std::string_view title, std::string_view message, std::string_v [ self internalMouseButtonEvent ]; } } + +/** + * Handler of left mouse button releasing. + * @param event Information about occurred event. + */ - (void)mouseUp:(NSEvent *)event { if (self->_emulated_down) { @@ -692,22 +728,40 @@ void CocoaDialog(std::string_view title, std::string_view message, std::string_v } } +/** + * Handler of mouse movement when right button is down. + * @param event Information about occurred event. + */ - (void)rightMouseDragged:(NSEvent *)event { [ self internalMouseMoveEvent:event ]; } + +/** + * Handler of right mouse button pressing. + * @param event Information about occurred event. + */ - (void)rightMouseDown:(NSEvent *)event { _right_button_down = true; _right_button_clicked = true; [ self internalMouseButtonEvent ]; } + +/** + * Handler of right mouse button releasing. + * @param event Information about occurred event. + */ - (void)rightMouseUp:(NSEvent *)event { _right_button_down = false; [ self internalMouseButtonEvent ]; } +/** + * Handler of mouse wheel scrolling. + * @param event Information about occurred event. + */ - (void)scrollWheel:(NSEvent *)event { if ([ event deltaY ] > 0.0) { /* Scroll up */ @@ -737,6 +791,10 @@ void CocoaDialog(std::string_view title, std::string_view message, std::string_v _cursor.wheel_moved = true; } +/** + * Handler of magnification events. + * @param event Information about occurred event. + */ - (void)magnifyWithEvent:(NSEvent *)event { /* Pinch open or close gesture. */ @@ -754,6 +812,10 @@ void CocoaDialog(std::string_view title, std::string_view message, std::string_v } } +/** + * Handler of gesture to end magnification. + * @param event Information about occurred event. + */ - (void)endGestureWithEvent:(NSEvent *)event { /* Gesture ended. */ @@ -761,6 +823,11 @@ void CocoaDialog(std::string_view title, std::string_view message, std::string_v } +/** + * Internal handler of keyboard keys. + * @param event Information about occurred event. + * @return Whether event should be interpreted. + */ - (BOOL)internalHandleKeycode:(unsigned short)keycode unicode:(char32_t)unicode pressed:(BOOL)down modifiers:(NSUInteger)modifiers { switch (keycode) { @@ -833,6 +900,10 @@ void CocoaDialog(std::string_view title, std::string_view message, std::string_v return interpret_keys; } +/** + * Handler of keyboard key pressing. + * @param event Information about occurred event. + */ - (void)keyDown:(NSEvent *)event { /* Quit, hide and minimize */ @@ -862,6 +933,10 @@ void CocoaDialog(std::string_view title, std::string_view message, std::string_v } } +/** + * Handler of keyboard key releasing. + * @param event Information about occurred event. + */ - (void)keyUp:(NSEvent *)event { /* Quit, hide and minimize */ @@ -882,6 +957,10 @@ void CocoaDialog(std::string_view title, std::string_view message, std::string_v [ self internalHandleKeycode:event.keyCode unicode:unicode_str[0] pressed:NO modifiers:event.modifierFlags ]; } +/** + * Handler of modifiers. + * @param event Information about occurred event. + */ - (void)flagsChanged:(NSEvent *)event { const int mapping[] = { QZ_CAPSLOCK, QZ_LSHIFT, QZ_LCTRL, QZ_LALT, QZ_LMETA }; @@ -1082,141 +1161,210 @@ void CocoaDialog(std::string_view title, std::string_view message, std::string_v return [ NSArray array ]; } -/** Delete single character left of the cursor. */ +/** + * Delete single character left of the cursor. + * @param sender Where the event comes from. + */ - (void)deleteBackward:(id)sender { if (EditBoxInGlobalFocus()) HandleKeypress(WKC_BACKSPACE, 0); } -/** Delete word left of the cursor. */ +/** + * Delete word left of the cursor. + * @param sender Where the event comes from. + */ - (void)deleteWordBackward:(id)sender { if (EditBoxInGlobalFocus()) HandleKeypress(WKC_BACKSPACE | WKC_CTRL, 0); } -/** Delete single character right of the cursor. */ +/** + * Delete single character right of the cursor. + * @param sender Where the event comes from. + */ - (void)deleteForward:(id)sender { if (EditBoxInGlobalFocus()) HandleKeypress(WKC_DELETE, 0); } -/** Delete word right of the cursor. */ +/** + * Delete word right of the cursor. + * @param sender Where the event comes from. + */ - (void)deleteWordForward:(id)sender { if (EditBoxInGlobalFocus()) HandleKeypress(WKC_DELETE | WKC_CTRL, 0); } -/** Move cursor one character left. */ +/** + * Move cursor one character left. + * @param sender Where the event comes from. + */ - (void)moveLeft:(id)sender { if (EditBoxInGlobalFocus()) HandleKeypress(WKC_LEFT, 0); } -/** Move cursor one word left. */ +/** + * Move cursor one word left. + * @param sender Where the event comes from. + */ - (void)moveWordLeft:(id)sender { if (EditBoxInGlobalFocus()) HandleKeypress(WKC_LEFT | WKC_CTRL, 0); } -/** Move cursor one character right. */ +/** + * Move cursor one character right. + * @param sender Where the event comes from. + */ - (void)moveRight:(id)sender { if (EditBoxInGlobalFocus()) HandleKeypress(WKC_RIGHT, 0); } -/** Move cursor one word right. */ +/** + * Move cursor one word right. + * @param sender Where the event comes from. + */ - (void)moveWordRight:(id)sender { if (EditBoxInGlobalFocus()) HandleKeypress(WKC_RIGHT | WKC_CTRL, 0); } -/** Move cursor one line up. */ +/** + * Move cursor one line up. + * @param sender Where the event comes from. + */ - (void)moveUp:(id)sender { if (EditBoxInGlobalFocus()) HandleKeypress(WKC_UP, 0); } -/** Move cursor one line down. */ +/** + * Move cursor one line down. + * @param sender Where the event comes from. + */ - (void)moveDown:(id)sender { if (EditBoxInGlobalFocus()) HandleKeypress(WKC_DOWN, 0); } -/** MScroll one line up. */ +/** + * MScroll one line up. + * @param sender Where the event comes from. + */ - (void)moveUpAndModifySelection:(id)sender { if (EditBoxInGlobalFocus()) HandleKeypress(WKC_UP | WKC_SHIFT, 0); } -/** Scroll one line down. */ +/** + * Scroll one line down. + * @param sender Where the event comes from. + */ - (void)moveDownAndModifySelection:(id)sender { if (EditBoxInGlobalFocus()) HandleKeypress(WKC_DOWN | WKC_SHIFT, 0); } -/** Move cursor to the start of the line. */ +/** + * Move cursor to the start of the line. + * @param sender Where the event comes from. + */ - (void)moveToBeginningOfLine:(id)sender { if (EditBoxInGlobalFocus()) HandleKeypress(WKC_HOME, 0); } -/** Move cursor to the end of the line. */ +/** + * Move cursor to the end of the line. + * @param sender Where the event comes from. + */ - (void)moveToEndOfLine:(id)sender { if (EditBoxInGlobalFocus()) HandleKeypress(WKC_END, 0); } -/** Scroll one page up. */ +/** + * Scroll one page up. + * @param sender Where the event comes from. + */ - (void)scrollPageUp:(id)sender { if (EditBoxInGlobalFocus()) HandleKeypress(WKC_PAGEUP, 0); } -/** Scroll one page down. */ +/** + * Scroll one page down. + * @param sender Where the event comes from. + */ - (void)scrollPageDown:(id)sender { if (EditBoxInGlobalFocus()) HandleKeypress(WKC_PAGEDOWN, 0); } -/** Move cursor (and selection) one page up. */ +/** + * Move cursor (and selection) one page up. + * @param sender Where the event comes from. + */ - (void)pageUpAndModifySelection:(id)sender { if (EditBoxInGlobalFocus()) HandleKeypress(WKC_PAGEUP | WKC_SHIFT, 0); } -/** Move cursor (and selection) one page down. */ +/** + * Move cursor (and selection) one page down. + * @param sender Where the event comes from. + */ - (void)pageDownAndModifySelection:(id)sender { if (EditBoxInGlobalFocus()) HandleKeypress(WKC_PAGEDOWN | WKC_SHIFT, 0); } -/** Scroll to the beginning of the document. */ +/** + * Scroll to the beginning of the document. + * @param sender Where the event comes from. + */ - (void)scrollToBeginningOfDocument:(id)sender { /* For compatibility with OTTD on Win/Linux. */ [ self moveToBeginningOfLine:sender ]; } -/** Scroll to the end of the document. */ +/** + * Scroll to the end of the document. + * @param sender Where the event comes from. + */ - (void)scrollToEndOfDocument:(id)sender { /* For compatibility with OTTD on Win/Linux. */ [ self moveToEndOfLine:sender ]; } -/** Return was pressed. */ +/** + * Return was pressed. + * @param sender Where the event comes from. + */ - (void)insertNewline:(id)sender { if (EditBoxInGlobalFocus()) HandleKeypress(WKC_RETURN, '\r'); } -/** Escape was pressed. */ +/** + * Escape was pressed. + * @param sender Where the event comes from. + */ - (void)cancelOperation:(id)sender { if (EditBoxInGlobalFocus()) HandleKeypress(WKC_ESC, 0); } -/** Invoke the selector if we implement it. */ +/** + * Invoke the selector if we implement it. + * @param aSelector The selector to invoke. + */ - (void)doCommandBySelector:(SEL)aSelector { if ([ self respondsToSelector:aSelector ]) [ self performSelector:aSelector ]; @@ -1237,7 +1385,10 @@ void CocoaDialog(std::string_view title, std::string_view message, std::string_v } return self; } -/** Handle closure requests */ +/** + * Handle closure requests + * @param sender Where the event comes from. + */ - (BOOL)windowShouldClose:(id)sender { HandleExitGameRequest(); @@ -1276,4 +1427,4 @@ void CocoaDialog(std::string_view title, std::string_view message, std::string_v @end -#endif /* WITH_COCOA */ +#endif /* WITH_COCOA or DOXYGEN_API */