diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/Fl.cxx | 150 | ||||
| -rw-r--r-- | src/Fl_Window.cxx | 140 | ||||
| -rw-r--r-- | src/makedepend | 3 | ||||
| -rw-r--r-- | src/screen_xywh.cxx | 26 |
4 files changed, 218 insertions, 101 deletions
diff --git a/src/Fl.cxx b/src/Fl.cxx index e65cad949..bae7f1328 100644 --- a/src/Fl.cxx +++ b/src/Fl.cxx @@ -164,6 +164,7 @@ void Fl::scrollbar_size(int W) { /** Gets the default line spacing used by menus. \returns The default line spacing, in pixels. + \since 1.4.0 */ int Fl::menu_linespacing() { return menu_linespacing_; @@ -173,6 +174,7 @@ int Fl::menu_linespacing() { Sets the default line spacing used by menus. Default is 4. \param[in] H The new default line spacing between menu items, in pixels. + \since 1.4.0 */ void Fl::menu_linespacing(int H) { menu_linespacing_ = H; @@ -872,19 +874,23 @@ void Fl::add_handler(Fl_Event_Handler ha) { } -/** Returns the last function installed by a call to Fl::add_handler() */ +/** Returns the last function installed by a call to Fl::add_handler(). + + \since 1.4.0 +*/ Fl_Event_Handler Fl::last_handler() { return handlers ? handlers->handle : NULL; } /** Install a function to parse unrecognized events with less priority than another function. - Install function \p ha to handle unrecognized events - giving it the priority just lower than that of function \p before - which was previously installed. - \see Fl::add_handler(Fl_Event_Handler) - \see Fl::last_handler() - */ + Install function \p ha to handle unrecognized events + giving it the priority just lower than that of function \p before + which was previously installed. + \see Fl::add_handler(Fl_Event_Handler) + \see Fl::last_handler() + \since 1.4.0 +*/ void Fl::add_handler(Fl_Event_Handler ha, Fl_Event_Handler before) { if (!before) return Fl::add_handler(ha); handler_link *l = handlers; @@ -1028,10 +1034,10 @@ Fl_Widget* fl_oldfocus; // kludge for Fl_Group... \e test if the widget wants the focus (by it returning non-zero from handle()). - Widgets can set the NEEDS_KEYBOARD flag to indicate that a keyboard is - essential for the widget to function. Touchscreen devices will be sent a - request to show an on-screen keyboard if no hardware keyboard is - connected. + Since FLTK 1.4.0 widgets can set the NEEDS_KEYBOARD flag to indicate that + a keyboard is essential for the widget to function. Touchscreen devices + will be sent a request to show an on-screen keyboard if no hardware keyboard + is connected. \see Fl_Widget::take_focus() \see Fl_Widget::needs_keyboard() const @@ -1273,9 +1279,11 @@ static int send_event(int event, Fl_Widget* to, Fl_Window* window) { } /** - \brief Give the reason for calling a callback. - \return the reason for the current callback - \see Fl_Widget::when(), Fl_Widget::do_callback(), Fl_Widget::callback() + Give the reason for calling a callback. + + \return the reason for the current callback + \see Fl_Widget::when(), Fl_Widget::do_callback(), Fl_Widget::callback() + \since 1.4.0 */ Fl_Callback_Reason Fl::callback_reason() { return callback_reason_; @@ -2109,27 +2117,27 @@ bool Fl::option(Fl_Option opt) } /** - \brief Override an option while the application is running. + Override an option while the application is running. - Apps can override the machine settings and the user settings by calling - `Fl::option(option, bool)`. The override takes effect immediately for this - option for all widgets in the app for the life time of the app. + Apps can override the machine settings and the user settings by calling + `Fl::option(option, bool)`. The override takes effect immediately for this + option for all widgets in the app for the life time of the app. - The override is not saved anywhere, and relaunching the app will restore the - old settings. + The override is not saved anywhere, and relaunching the app will restore the + old settings. - Example: - \code - Fl::option(Fl::OPTION_ARROW_FOCUS, true); // on - Fl::option(Fl::OPTION_ARROW_FOCUS, false); // off - \endcode + Example: + \code + Fl::option(Fl::OPTION_ARROW_FOCUS, true); // on + Fl::option(Fl::OPTION_ARROW_FOCUS, false); // off + \endcode - \param opt which option - \param val set to true or false + \param opt which option + \param val set to true or false \see enum Fl::Fl_Option \see bool Fl::option(Fl_Option) - */ +*/ void Fl::option(Fl_Option opt, bool val) { if (opt<0 || opt>=OPTION_LAST) @@ -2281,16 +2289,24 @@ void fl_close_display() } #ifdef FL_DOXYGEN -/** Prevent the FLTK library from using its Wayland backend and forces it to use its X11 backend. - Put this declaration somewhere in your code outside the body of any function : - \code - FL_EXPORT bool fl_disable_wayland = true; - \endcode - This declaration makes sure source code developed for FLTK 1.3, including X11-specific code, - will build and run with FLTK 1.4 and its Wayland platform with this single source code level change. - This declaration has no effect on non-Wayland platforms. - Don't put this declaration if you want the Wayland backend to be used when it's available. - */ +/** Prevent the FLTK library from using its Wayland backend and force it to use its X11 backend. + + Put this declaration somewhere in your source code outside the body of any function: + \code + FL_EXPORT bool fl_disable_wayland = true; + \endcode + This declaration makes sure that source code developed for FLTK 1.3, including + X11-specific code, will build and run with FLTK 1.4 and its Wayland platform + with a single line source code level change. + This declaration has no effect on non-Wayland platforms. + Don't add this declaration if you want the Wayland backend to be used when + it's available. + + \note Please see also chapter 2.1 of README.Wayland.txt for further information + on how to build your application to ensure that this declaration is effective. + + \since 1.4.0 +*/ FL_EXPORT bool fl_disable_wayland = true; #endif // FL_DOXYGEN @@ -2331,15 +2347,44 @@ int Fl::get_font_sizes(Fl_Font fnum, int*& sizep) { return Fl_Graphics_Driver::default_driver().get_font_sizes(fnum, sizep); } -/** Current value of the GUI scaling factor for screen number \p n (n ∈ [0 , Fl::screen_count()-1]) */ +/** Gets the GUI scaling factor of screen number \p n. + + The valid range of \p n is 0 .. Fl::screen_count() - 1. + + The return value is \c 1.0 if screen scaling is not supported or + \p n is outside the valid range. + + \return Current screen scaling factor (default: \c 1.0) + + \see Fl::screen_count() + \see Fl::screen_scaling_supported() + + \since 1.4.0 +*/ float Fl::screen_scale(int n) { - if (!Fl::screen_scaling_supported() || n < 0 || n >= Fl::screen_count()) return 1.; + if (!Fl::screen_scaling_supported() || n < 0 || n >= Fl::screen_count()) + return 1.; return Fl::screen_driver()->scale(n); } -/** Sets the value of the GUI scaling factor for screen number \p n (n ∈ [0 , Fl::screen_count()-1]). - Also sets the scale factor value of all windows mapped to screen number \p n, if any. - */ +/** Sets the GUI scaling factor of screen number \p n. + + The valid range of \p n is 0 .. Fl::screen_count() - 1. + + This method does nothing if \p n is out of range or screen scaling + is not supported by this platform. + + Otherwise it also sets the scaling factor of all windows mapped to + screen number \p n or all screens, depending on the type of screen + scaling support on the platform. + + \param[in] n screen number + \param[in] factor scaling factor of screen \p n + + \see Fl::screen_scaling_supported() + + \since 1.4.0 +*/ void Fl::screen_scale(int n, float factor) { Fl_Screen_Driver::APP_SCALING_CAPABILITY capability = Fl::screen_driver()->rescalable(); if (!capability || n < 0 || n >= Fl::screen_count()) return; @@ -2347,16 +2392,21 @@ void Fl::screen_scale(int n, float factor) { for (int s = 0; s < Fl::screen_count(); s++) { Fl::screen_driver()->rescale_all_windows_from_screen(s, factor, factor); } - } else Fl::screen_driver()->rescale_all_windows_from_screen(n, factor, factor); + } else + Fl::screen_driver()->rescale_all_windows_from_screen(n, factor, factor); } /** - See if scaling factors are supported by this platform. - \return 0 if scaling factors are not supported by this platform, - 1 if a single scaling factor value is shared by all screens, 2 if each screen - can have its own scaling factor value. + Returns whether scaling factors are supported by this platform. + + \retval 0 scaling factors are not supported by this platform + \retval 1 a single scaling factor is shared by all screens + \retval 2 each screen can have its own scaling factor + \see Fl::screen_scale(int) - */ + + \since 1.4.0 +*/ int Fl::screen_scaling_supported() { return Fl::screen_driver()->rescalable(); } @@ -2373,6 +2423,8 @@ int Fl::screen_scaling_supported() { \param value 0 to stop recognition of ctrl/+/-/0/ (or cmd/+/-/0/ under macOS) keys as window scaling. + + \since 1.4.0 */ void Fl::keyboard_screen_scaling(int value) { Fl_Screen_Driver::keyboard_screen_scaling = value; diff --git a/src/Fl_Window.cxx b/src/Fl_Window.cxx index c0dad7e37..d5a82a41b 100644 --- a/src/Fl_Window.cxx +++ b/src/Fl_Window.cxx @@ -1,7 +1,7 @@ // // Window widget class for the Fast Light Tool Kit (FLTK). // -// Copyright 1998-2022 by Bill Spitzak and others. +// Copyright 1998-2024 by Bill Spitzak and others. // // This library is free software. Distribution and use rights are outlined in // the file "COPYING" which should have been included with this file. If this @@ -679,16 +679,19 @@ void Fl_Window::size_range(int minWidth, int minHeight, } /** - Gets the allowable range to which the user can resize this window. + Gets the allowable range to which the user can resize this window. - \param[out] minWidth, minHeight, maxWidth, maxHeight, deltaX, deltaY, aspectRatio + \param[out] minWidth, minHeight, maxWidth, maxHeight, deltaX, deltaY, aspectRatio are all pointers to integers that will receive the current respective value during the call. Every pointer can be NULL if that value is not needed. - \retval 0 if size range not set - \retval 1 if the size range was explicitly set by a call to Fl_Window::size_range() - or has been calculated - \see Fl_Window::size_range(int minWidth, int minHeight, int maxWidth, int maxHeight, int deltaX, int deltaY, int aspectRatio) - */ + + \retval 0 if size range not set + \retval 1 if the size range was explicitly set by a call to Fl_Window::size_range() + or has been calculated + \see Fl_Window::size_range(int minWidth, int minHeight, int maxWidth, int maxHeight, int deltaX, int deltaY, int aspectRatio) + + \since 1.4.0 +*/ uchar Fl_Window::get_size_range(int *minWidth, int *minHeight, int *maxWidth, int *maxHeight, int *deltaX, int *deltaY, int *aspectRatio) { @@ -780,6 +783,8 @@ uchar Fl_Window::get_size_range(int *minWidth, int *minHeight, If this is not what you want, please use Fl_Window::size_range() explicitly so you can set any appropriate range. + + \since 1.4.0 */ void Fl_Window::default_size_range() { @@ -859,6 +864,8 @@ void Fl_Window::default_size_range() { \retval 3 the window is resizable in both directions (w and h) \see default_size_range() + + \since 1.4.0 */ int Fl_Window::is_resizable() { default_size_range(); @@ -868,27 +875,59 @@ int Fl_Window::is_resizable() { return ret; } -/** The number of the screen containing the mapped window */ +/** The number of the screen containing the mapped window. + + This method returns the screen number (0 .. n) of the window + if it is shown, otherwise the result value is undefined. + + \note The return value is undefined before the window is shown and + if the window has been hidden after it was previously shown. + + To position a window on a particular screen, use + Fl_Window::screen_num(int) \b before you show() it. + + \return screen number of the window if it is shown + + \see Fl_Window::screen_num(int) + + \since 1.4.0 + */ int Fl_Window::screen_num() { return pWindowDriver->screen_num(); } /** Set the number of the screen where to map the window. - Call this and set also the window's desired position before show()'ing the window. - This can be necessary when a system has several screens with - distinct scaling factor values because the window's x() and y() may not suffice to - uniquely identify one screen. - To see that, consider a system with two screens where the screen at left is A pixel-wide - and has a scale factor of 1 whereas the screen at right has a scale factor of 2. - For the sake of simplicity, consider only - the X coordinates of windows. FLTK coordinates translate directly to pixel coordinates on the - left screen, whereas FLTK coordinates multiplied by 2 correspond to pixel coordinates - on the right screen. Consequently, FLTK coordinates between A/2 + 1 and A-1 can map to both - screens. Both window coordinates and screen number are necessary to uniquely identify - where a window is to be mapped. - */ + + Call this and set also the window's desired x/y position before show()'ing + the window. This can be necessary if a system has several screens with + distinct scaling factors because the window's x() and y() may not suffice + to uniquely identify one screen. + + Consider a system with two screens where the left screen is A pixels wide and + has a scaling factor of 1 whereas the right screen has a scaling factor of 2. + For the sake of simplicity, consider only the X coordinate of the window. + FLTK coordinates translate directly to pixel coordinates on the left screen, + whereas FLTK coordinates multiplied by 2 correspond to pixel coordinates + on the right screen. Consequently, FLTK coordinates between A/2 + 1 and A-1 + can map to both screens. Therefore both the window coordinates and the screen + number are necessary to uniquely identify where a window is to be mapped. + + The valid range of \p screen_num is 0 .. Fl::screen_count() - 1. + + This method does nothing if + - the window is already shown() or + - the given screen number is out of range. + + \param[in] screen_num screen number where the window is to be mapped + + \see Fl_Window::screen_num() + \see Fl::screen_count() + + \since 1.4.0 +*/ void Fl_Window::screen_num(int screen_num) { - if (!shown() && screen_num >= 0 && screen_num < Fl::screen_count()) pWindowDriver->screen_num(screen_num); + if (!shown() && screen_num >= 0 && screen_num < Fl::screen_count()) + pWindowDriver->screen_num(screen_num); } /** Assigns a non-rectangular shape to the window. @@ -934,29 +973,43 @@ void Fl_Window::shape(const Fl_Image* img) {pWindowDriver->shape(img);} */ void Fl_Window::shape(const Fl_Image& img) {pWindowDriver->shape(&img);} -/** Returns the image controlling the window shape or NULL */ +/** Returns the image controlling the window shape or NULL. + + \since 1.4.0 +*/ const Fl_Image* Fl_Window::shape() {return pWindowDriver->shape();} -/** Returns true when a window is being rescaled */ +/** Returns true when a window is being rescaled. + + \since 1.4.0 +*/ bool Fl_Window::is_a_rescale() {return Fl_Window_Driver::is_a_rescale_;} /** Returns a platform-specific identification of a shown window, or 0 if not shown. - \note This identification may differ from the platform-specific reference of an - Fl_Window object used by functions fl_x11_xid(), fl_mac_xid(), fl_x11_find(), and fl_mac_find(). - \li X11 platform: the window's XID. - \li macOS platform: The window number of the window’s window device. - \li other platforms: 0. - */ + + \note This identification may differ from the platform-specific reference + of an Fl_Window object used by functions fl_x11_xid(), fl_mac_xid(), + fl_x11_find(), and fl_mac_find(). + + - X11 platform: the window's XID. + - macOS platform: The window number of the window’s window device. + - other platforms: 0. + + \since 1.4.0 +*/ fl_uintptr_t Fl_Window::os_id() { return pWindowDriver->os_id();} /** - Maximizes a top-level window to its current screen. + Maximizes a top-level window to its current screen. - This function is effective only with a show()'n, resizable, top-level window. - Bordered and borderless windows can be used. - Fullscreen windows can't be used. - \see Fl_Window::un_maximize(), Fl_Window::maximize_active() - */ + This function is effective only with a show()'n, resizable, top-level window. + Bordered and borderless windows can be used. + Fullscreen windows can't be used. + + \see Fl_Window::un_maximize(), Fl_Window::maximize_active() + + \since 1.4.0 +*/ void Fl_Window::maximize() { if (!shown() || parent() || !is_resizable() || maximize_active() || fullscreen_active()) return; @@ -965,8 +1018,10 @@ void Fl_Window::maximize() { } /** - Returns a previously maximized top-level window to its previous size. - \see Fl_Window::maximize() + Returns a previously maximized top-level window to its previous size. + \see Fl_Window::maximize() + + \since 1.4.0 */ void Fl_Window::un_maximize() { if (!shown() || parent() || !is_resizable() || !maximize_active() || fullscreen_active()) return; @@ -980,8 +1035,11 @@ void Fl_Window::is_maximized_(bool b) { } /** Allow this subwindow to expand outside the area of its parent window. - This is presently implemented only for the Wayland platform to help support window docking. - \since 1.4.0 + + This is presently implemented only for the Wayland platform to help + support window docking. + + \since 1.4.0 */ void Fl_Window::allow_expand_outside_parent() { if (parent()) pWindowDriver->allow_expand_outside_parent(); diff --git a/src/makedepend b/src/makedepend index ad5891342..b2b83a6f5 100644 --- a/src/makedepend +++ b/src/makedepend @@ -3701,6 +3701,7 @@ fl_shortcut.o: Fl_Screen_Driver.H fl_shortcut.o: Fl_System_Driver.H Fl_Shortcut_Button.o: ../config.h Fl_Shortcut_Button.o: ../FL/Enumerations.H +Fl_Shortcut_Button.o: ../FL/filename.H Fl_Shortcut_Button.o: ../FL/Fl.H Fl_Shortcut_Button.o: ../FL/fl_attr.h Fl_Shortcut_Button.o: ../FL/Fl_Button.H @@ -3709,6 +3710,7 @@ Fl_Shortcut_Button.o: ../FL/fl_casts.H Fl_Shortcut_Button.o: ../FL/fl_config.h Fl_Shortcut_Button.o: ../FL/fl_draw.H Fl_Shortcut_Button.o: ../FL/Fl_Export.H +Fl_Shortcut_Button.o: ../FL/Fl_Preferences.H Fl_Shortcut_Button.o: ../FL/Fl_Shortcut_Button.H Fl_Shortcut_Button.o: ../FL/fl_string_functions.h Fl_Shortcut_Button.o: ../FL/fl_types.h @@ -3716,6 +3718,7 @@ Fl_Shortcut_Button.o: ../FL/fl_utf8.h Fl_Shortcut_Button.o: ../FL/Fl_Widget.H Fl_Shortcut_Button.o: ../FL/platform_types.h Fl_Shortcut_Button.o: flstring.h +Fl_Shortcut_Button.o: Fl_System_Driver.H fl_show_colormap.o: ../config.h fl_show_colormap.o: ../FL/Enumerations.H fl_show_colormap.o: ../FL/Fl.H diff --git a/src/screen_xywh.cxx b/src/screen_xywh.cxx index 604611d6b..60ad00287 100644 --- a/src/screen_xywh.cxx +++ b/src/screen_xywh.cxx @@ -1,7 +1,7 @@ // // Screen/monitor bounding box API for the Fast Light Tool Kit (FLTK). // -// Copyright 1998-2018 by Bill Spitzak and others. +// Copyright 1998-2024 by Bill Spitzak and others. // // This library is free software. Distribution and use rights are outlined in // the file "COPYING" which should have been included with this file. If this @@ -57,7 +57,7 @@ int Fl::h() /** Gets the total count of available screens. - \note Screen numbers range from 0 to Fl::screen_count()-1 in the FLTK API. + \note Screen numbers range from 0 to Fl::screen_count() - 1 in the FLTK API. */ int Fl::screen_count() { @@ -133,13 +133,16 @@ void Fl::screen_xywh(int &X, int &Y, int &W, int &H, int mx, int my, int mw, int /** - Gets the screen number of a screen - that contains the specified screen position \p x, \p y + Gets the screen number of a screen that contains the specified + screen position \p x, \p y. + \param[in] x, y the absolute screen position \return a screen number ∈ [0 , Fl::screen_count()-1] - \attention When the running system contains screens with different scaling factor values, this API - may become ambiguous because a given value pair (\p x, \p y) may belong to distinct screens. - In that situation, other APIs should be preferred, e.g., Fl_Window::screen_num() and Fl::screen_scale(int). + + \attention When the running system contains screens with different scaling + factors, this API may become ambiguous because a given value pair (\p x, \p y) + may belong to distinct screens. In that situation other APIs should be + preferred, e.g. Fl_Window::screen_num() and Fl::screen_scale(int). */ int Fl::screen_num(int x, int y) { @@ -148,12 +151,13 @@ int Fl::screen_num(int x, int y) /** - Gets the screen number for the screen - which intersects the most with the rectangle - defined by \p x, \p y, \p w, \p h. + Gets the screen number of the screen which intersects the most with + the rectangle defined by \p x, \p y, \p w, \p h. + \param[in] x, y, w, h the rectangle to search for intersection with + \return a screen number ∈ [0 , Fl::screen_count()-1] - */ +*/ int Fl::screen_num(int x, int y, int w, int h) { return screen_driver()->screen_num(x, y, w, h); |