From 2d18c6f650c0001319c8883f8deb819d12984ac0 Mon Sep 17 00:00:00 2001 From: engelsman Date: Wed, 8 Dec 2021 15:00:33 +0100 Subject: Documentation on widget coordinates and layout, plus new test programs (#304) Add coordinates and layout section to user manual add section to user manual to clarify the use of window-relative coordinates in both Fl_Group and Fl_Window containers, and include brief descriptions of current layout manager widgets in one place. add test/coordinates.cxx, test/wizard.cxx and related screenshots under documentation/src. update CMakeLists.txt, Makefile and .gitignore for new files. Co-authored-by: Albrecht Schlosser --- documentation/src/coordinates.dox | 171 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 documentation/src/coordinates.dox (limited to 'documentation/src/coordinates.dox') diff --git a/documentation/src/coordinates.dox b/documentation/src/coordinates.dox new file mode 100644 index 000000000..ca996e64e --- /dev/null +++ b/documentation/src/coordinates.dox @@ -0,0 +1,171 @@ +/** + + \page coordinates Coordinates and Layout Widgets + +This chapter describes the coordinate systems that apply when +positioning widgets manually, and some of the basics of FLTK +layout widgets that are used to position widgets automatically. + + +\section coordinates_coordinates The widget coordinate system + +All widgets have constructors with \p x and \p y parameters to +let the programmer specify the desired initial position of the +top left corner during explicit manual layout within Fl_Window +and Fl_Group container widgets. + +This position is always relative to the enclosing Fl_Window, +which is usually, but not always, the top-level application +window, or a free-floating pop-up dialog window. +In some cases it could also be a subwindow embedded in a +higher-level window, as shown in the figure below. + +\image html coordinates.png "FLTK coordinate system" +\image latex coordinates.png "FLTK coordinate system" width=6cm + +The positions of the TL and BR sub-windows and the TR and BL +groups are all relative to the top-left corner of the main window. +The positions of the boxes inside the TR and BL groups are also +relative to the main window, but the boxes inside the TL and BR +sub-windows are positioned relative to the enclosing sub-window. + +In other words, the widget hierarchy and positions can be summarized as: +
+    Fl_Window main window
+      Fl_Window TL subwindow     # x, y relative to main window
+        Fl_Box  tl box           # x, y relative to TL subwindow
+      Fl_Window BR subwindow     # x, y relative to main window
+        Fl_Box  br box           # x, y relative to BR subwindow
+      Fl_Group  TR group         # x, y relative to main window
+        Fl_Box  tr box           # x, y relative to main window
+      Fl_Group  BL group         # x, y relative to main window
+        Fl_Box  bl box           # x, y relative to main window
+
+ + +\section coordinate_layout Layout and container widgets + +There are four main groups of widgets derived from Fl_Group for +a range of different purposes. + +The first group are composite widgets that each contain a fixed +set of components that work together for a specific purpose, +rather than layout widgets as such, and are not discussed here. + +The second group are basically containers offering the same manual +layout features as Fl_Group, as described above, but which add one +new capability. These widgets are Fl_Scroll, Fl_Tabs and Fl_Wizard. + +The third group are layout managers that relocate and resize the +child widgets added to them in order to satisfy a particular layout +algorithm. These widgets are Fl_Pack and Fl_Tile. + +The final group consists of Fl_Window and its derivatives. +Their special capability is that they can be top-level application +windows and dialogs that interface with the operating system window +manager, but can also be embedded within other windows and groups +as shown in the example above. +Note that the window manager may impose its own constraints on +the position of top-level windows, and the \p x and \p y +position parameters may be treated as hints, or even ignored. +The Fl_Window class has an extra constructor that omits them. + + +\subsection coordinates_pack The Fl_Pack layout widget + +The Fl_Pack widget allows the layout of its direct children as a +single row, or column. +If its type() is set to give the row or horizontal layout, +the children are all resized to have the same height as the Fl_Pack +and are moved next to each other. +If set to give the column or vertical layout, the children are all +resized to have the same width as the Fl_Pack and are then stacked +below each other. +The Fl_Pack then resizes itself to shrink-wrap itself around all +of the children. + +Fl_Pack widgets are often used inside an Fl_Scroll, as shown in the +diagram below, to avoid having to deal with tricky resize behavior +when used with nested widgets. + +\image html pack.png "Fl_Pack test program screenshot" +\image latex pack.png "Fl_Pack test program screenshot" width=8cm + + +\subsection coordinates_scroll The Fl_Scroll container widget + +The Fl_Scroll container widget can hold an assortment of widgets +that may extend beyond its own width and height, in which case +horizontal and/or vertical scrollbars may appear automatically +so that you can scroll and view the entire contents. + +\image html Fl_Scroll.png "Fl_Scroll container widget" +\image latex Fl_Scroll.png "Fl_Scroll container widget" width=4cm + + +\subsection coordinates_tabs The Fl_Tabs container widget + +The Fl_Tabs widget provides a front-to-back stack of individual +panels which usually contain Fl_Group widgets and their children. +The user can switch between panels by clicking on the small +tabs that protrude from the panels. The appearance of each tab +is determined by the child widget's label and related attributes. + +\image html tabs.png "Fl_Tabs container widget" +\image latex tabs.png "Fl_Tabs container widget" width=8cm + + +\subsection coordinates_tile The Fl_Tile layout widget + +The Fl_Tile widget allows the user to resize one or more of its children +by dragging on the border between adjacent child widgets. +However, the programmer must first explicitly layout the child widgets +so that their borders exactly fill the width and height of the Fl_Tile +without having any gaps between them, or at the edges. +Some care is needed when initially positioning the children and setting +the resizable() widget within the Fl_Tile to prevent squeezing a child +to have a zero width or height. +For more information see the Fl_Tile widget manual page, and \ref resize. + + +\image html Fl_Tile.png "The Fl_Tile layout widget" +\image latex Fl_Tile.png "The Fl_Tile layout widget" width=4cm + + +\subsection coordinates_wizard The Fl_Wizard container widget + +The Fl_Wizard widget derives from the Fl_Tabs class, but instead +of having tabs that the user can click to select the corresponding +panel, the programmer uses the prev(), next() or value() methods +to show the appropriate panel. +For example, the user might be able to click on "Next" and "Prev" +navigation buttons or keys, as shown below. + +\image html wizard.png "FL_Wizard container widget" +\image latex wizard.png "FL_Wizard container widget" width=4cm + + +\htmlonly +
+ + + + + + +
+ + [Prev] + Common Widgets and Attributes + + + [Index] + + + How Does Resizing Work? + [Next] + +
+\endhtmlonly + +*/ -- cgit v1.2.3