gdb/tui/tui-layout.h

   1 /* TUI layout window management.
   2
   3    Copyright (C) 1998-2023 Free Software Foundation, Inc.
   4
   5    Contributed by Hewlett-Packard Company.
   6
   7    This file is part of GDB.
   8
   9    This program is free software; you can redistribute it and/or modify
  10    it under the terms of the GNU General Public License as published by
  11    the Free Software Foundation; either version 3 of the License, or
  12    (at your option) any later version.
  13
  14    This program is distributed in the hope that it will be useful,
  15    but WITHOUT ANY WARRANTY; without even the implied warranty of
  16    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17    GNU General Public License for more details.
  18
  19    You should have received a copy of the GNU General Public License
  20    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  21
  22 #ifndef TUI_TUI_LAYOUT_H
  23 #define TUI_TUI_LAYOUT_H
  24
  25 #include "ui-file.h"
  26
  27 #include "tui/tui.h"
  28 #include "tui/tui-data.h"
  29 #include "gdbsupport/iterator-range.h"
  30
  31 #include <unordered_map>
  32
  33 /* Values that can be returned when handling a request to adjust a
  34    window's size.  */
  35 enum tui_adjust_result
  36 {
  37   /* Requested window was not found here.  */
  38   NOT_FOUND,
  39   /* Window was found but not handled.  */
  40   FOUND,
  41   /* Window was found and handled.  */
  42   HANDLED
  43 };
  44
  45 /* The basic object in a TUI layout.  This represents a single piece
  46    of screen real estate.  Subclasses determine the exact
  47    behavior.  */
  48 class tui_layout_base
  49 {
  50 public:
  51
  52   DISABLE_COPY_AND_ASSIGN (tui_layout_base);
  53
  54   virtual ~tui_layout_base () = default;
  55
  56   /* Clone this object.  Ordinarily a layout is cloned before it is
  57      used, so that any necessary modifications do not affect the
  58      "skeleton" layout.  */
  59   virtual std::unique_ptr<tui_layout_base> clone () const = 0;
  60
  61   /* Change the size and location of this layout.  When
  62      PRESERVE_CMD_WIN_SIZE_P is true the current size of the TUI_CMD_WIN
  63      is preserved, otherwise, the TUI_CMD_WIN will resize just like any
  64      other window.  */
  65   virtual void apply (int x, int y, int width, int height,
  66                       bool preserve_cmd_win_size_p) = 0;
  67
  68   /* Return the minimum and maximum height or width of this layout.
  69      HEIGHT is true to fetch height, false to fetch width.  */
  70   virtual void get_sizes (bool height, int *min_value, int *max_value) = 0;
  71
  72   /* True if the topmost (for vertical layouts), or the leftmost (for
  73      horizontal layouts) item in this layout is boxed.  */
  74   virtual bool first_edge_has_border_p () const = 0;
  75
  76   /* True if the bottommost (for vertical layouts), or the rightmost (for
  77      horizontal layouts) item in this layout is boxed.  */
  78   virtual bool last_edge_has_border_p () const = 0;
  79
  80   /* Return the name of this layout's window, or nullptr if this
  81      layout does not represent a single window.  */
  82   virtual const char *get_name () const
  83   {
  84     return nullptr;
  85   }
  86
  87   /* Set the height of the window named NAME to NEW_HEIGHT, updating
  88      the sizes of the other windows around it.  */
  89   virtual tui_adjust_result set_height (const char *name, int new_height) = 0;
  90
  91   /* Set the width of the window named NAME to NEW_WIDTH, updating
  92      the sizes of the other windows around it.  */
  93   virtual tui_adjust_result set_width (const char *name, int new_width) = 0;
  94
  95   /* Remove some windows from the layout, leaving the command window
  96      and the window being passed in here.  */
  97   virtual void remove_windows (const char *name) = 0;
  98
  99   /* Replace the window named NAME in the layout with the window named
 100      NEW_WINDOW.  */
 101   virtual void replace_window (const char *name, const char *new_window) = 0;
 102
 103   /* Append the specification to this window to OUTPUT.  DEPTH is the
 104      depth of this layout in the hierarchy (zero-based).  */
 105   virtual void specification (ui_file *output, int depth) = 0;
 106
 107   /* Return a FINGERPRINT string containing an abstract representation of
 108      the location of the cmd window in this layout.
 109
 110      When called on a complete, top-level layout, the fingerprint will be a
 111      non-empty string made of 'V' and 'H' characters, followed by a single
 112      'C' character.  Each 'V' and 'H' represents a vertical or horizontal
 113      layout that must be passed through in order to find the cmd
 114      window.
 115
 116      Of course, layouts are built recursively, so, when called on a partial
 117      layout, if this object represents a single window, then either the
 118      empty string is returned (for non-cmd windows), or a string
 119      containing a single 'C' is returned.
 120
 121      For object representing layouts, if the layout contains the cmd
 122      window then we will get back a valid fingerprint string (contains 'V'
 123      and 'H', ends with 'C'), or, if this layout doesn't contain the cmd
 124      window, an empty string is returned.  */
 125   virtual std::string layout_fingerprint () const = 0;
 126
 127   /* Add all windows to the WINDOWS vector.  */
 128   virtual void get_windows (std::vector<tui_win_info *> *windows) = 0;
 129
 130   /* The most recent space allocation.  */
 131   int x = 0;
 132   int y = 0;
 133   int width = 0;
 134   int height = 0;
 135
 136 protected:
 137
 138   tui_layout_base () = default;
 139 };
 140
 141 /* A TUI layout object that displays a single window.  The window is
 142    given by name.  */
 143 class tui_layout_window : public tui_layout_base
 144 {
 145 public:
 146
 147   explicit tui_layout_window (const char *name)
 148     : m_contents (name)
 149   {
 150   }
 151
 152   DISABLE_COPY_AND_ASSIGN (tui_layout_window);
 153
 154   std::unique_ptr<tui_layout_base> clone () const override;
 155
 156   void apply (int x, int y, int width, int height,
 157               bool preserve_cmd_win_size_p) override;
 158
 159   const char *get_name () const override
 160   {
 161     return m_contents.c_str ();
 162   }
 163
 164   tui_adjust_result set_height (const char *name, int new_height) override
 165   {
 166     return m_contents == name ? FOUND : NOT_FOUND;
 167   }
 168
 169   tui_adjust_result set_width (const char *name, int new_width) override
 170   {
 171     return m_contents == name ? FOUND : NOT_FOUND;
 172   }
 173
 174   bool first_edge_has_border_p () const override;
 175
 176   bool last_edge_has_border_p () const override;
 177
 178   void remove_windows (const char *name) override
 179   {
 180   }
 181
 182   void replace_window (const char *name, const char *new_window) override;
 183
 184   void specification (ui_file *output, int depth) override;
 185
 186   std::string layout_fingerprint () const override;
 187
 188   /* See tui_layout_base::get_windows.  */
 189   void get_windows (std::vector<tui_win_info *> *windows) override
 190   {
 191     windows->push_back (m_window);
 192   }
 193
 194 protected:
 195
 196   void get_sizes (bool height, int *min_value, int *max_value) override;
 197
 198 private:
 199
 200   /* Type of content to display.  */
 201   std::string m_contents;
 202
 203   /* When a layout is applied, this is updated to point to the window
 204      object.  */
 205   tui_win_info *m_window = nullptr;
 206 };
 207
 208 /* A TUI layout that holds other layouts.  */
 209 class tui_layout_split : public tui_layout_base
 210 {
 211 public:
 212
 213   /* Create a new layout.  If VERTICAL is true, then windows in this
 214      layout will be arranged vertically.  */
 215   explicit tui_layout_split (bool vertical = true)
 216     : m_vertical (vertical)
 217   {
 218   }
 219
 220   DISABLE_COPY_AND_ASSIGN (tui_layout_split);
 221
 222   /* Add a new split layout to this layout.  WEIGHT is the desired
 223      size, which is relative to the other weights given in this
 224      layout.  */
 225   void add_split (std::unique_ptr<tui_layout_split> &&layout, int weight);
 226
 227   /* Add a new window to this layout.  NAME is the name of the window
 228      to add.  WEIGHT is the desired size, which is relative to the
 229      other weights given in this layout.  */
 230   void add_window (const char *name, int weight);
 231
 232   std::unique_ptr<tui_layout_base> clone () const override;
 233
 234   void apply (int x, int y, int width, int height,
 235               bool preserve_cmd_win_size_p) override;
 236
 237   tui_adjust_result set_height (const char *name, int new_height) override
 238   {
 239     /* Pass false as the final argument to indicate change of height.  */
 240     return set_size (name, new_height, false);
 241   }
 242
 243   tui_adjust_result set_width (const char *name, int new_width) override
 244   {
 245     /* Pass true as the final argument to indicate change of width.  */
 246     return set_size (name, new_width, true);
 247   }
 248
 249   bool first_edge_has_border_p () const override;
 250
 251   bool last_edge_has_border_p () const override;
 252
 253   void remove_windows (const char *name) override;
 254
 255   void replace_window (const char *name, const char *new_window) override;
 256
 257   void specification (ui_file *output, int depth) override;
 258
 259   std::string layout_fingerprint () const override;
 260
 261   /* See tui_layout_base::get_windows.  */
 262   void get_windows (std::vector<tui_win_info *> *windows) override
 263   {
 264     for (auto &item : m_splits)
 265       item.layout->get_windows (windows);
 266   }
 267
 268 protected:
 269
 270   void get_sizes (bool height, int *min_value, int *max_value) override;
 271
 272 private:
 273
 274   /* Used to implement set_height and set_width member functions.  When
 275      SET_WIDTH_P is true, set the width, otherwise, set the height of the
 276      window named NAME to NEW_SIZE, updating the sizes of the other windows
 277      around it as needed.  The result indicates if the window NAME was
 278      found and had its size adjusted, was found but was not adjusted, or
 279      was not found at all.  */
 280   tui_adjust_result set_size (const char *name, int new_size,
 281                               bool set_width_p);
 282
 283   /* Set the weights from the current heights (when m_vertical is true) or
 284      widths (when m_vertical is false).  */
 285   void set_weights_from_sizes ();
 286
 287   /* Structure used when resizing, or applying a layout.  An instance of
 288      this structure is created for each sub-layout.  */
 289   struct size_info
 290   {
 291     /* The calculated size for this sub-layout.  */
 292     int size;
 293
 294     /* The minimum and maximum sizes for this sub-layout, obtained by
 295        calling the get_sizes member function.  */
 296     int min_size;
 297     int max_size;
 298
 299     /* True if this window will share a box border with the previous
 300        window in the list.  */
 301     bool share_box;
 302   };
 303
 304   /* Used for debug, prints the contents of INFO using tui_debug_printf.
 305      Only call this when the global debug_tui is true.  */
 306   static void tui_debug_print_size_info (const std::vector<size_info> &info);
 307
 308   /* Used for debug, returns a string describing the current weight of each
 309      sub-layout.  */
 310   std::string tui_debug_weights_to_string () const;
 311
 312   struct split
 313   {
 314     /* The requested weight.  */
 315     int weight;
 316     /* The layout.  */
 317     std::unique_ptr<tui_layout_base> layout;
 318   };
 319
 320   /* The splits.  */
 321   std::vector<split> m_splits;
 322
 323   /* True if the windows in this split are arranged vertically.  */
 324   bool m_vertical;
 325 };
 326
 327 /* Add the specified window to the layout in a logical way.  This
 328    means setting up the most logical layout given the window to be
 329    added.  Only the source or disassembly window can be added this
 330    way.  */
 331 extern void tui_add_win_to_layout (enum tui_win_type);
 332
 333 /* Set the initial layout.  */
 334 extern void tui_set_initial_layout ();
 335
 336 /* Switch to the next layout.  */
 337 extern void tui_next_layout ();
 338
 339 /* Show the register window.  Like "layout regs".  */
 340 extern void tui_regs_layout ();
 341
 342 /* Remove some windows from the layout, leaving only the focused
 343    window and the command window; if no window has the focus, then
 344    some other window is chosen to remain.  */
 345 extern void tui_remove_some_windows ();
 346
 347 /* Apply the current layout.  When PRESERVE_CMD_WIN_SIZE_P is true the
 348    current size of the TUI_CMD_WIN is preserved, otherwise, the TUI_CMD_WIN
 349    will resize just like any other window.  */
 350 extern void tui_apply_current_layout (bool);
 351
 352 /* Adjust the window height of WIN to NEW_HEIGHT.  */
 353 extern void tui_adjust_window_height (struct tui_win_info *win,
 354                                       int new_height);
 355
 356 /* Adjust the window width of WIN to NEW_WIDTH.  */
 357 extern void tui_adjust_window_width (struct tui_win_info *win,
 358                                      int new_width);
 359
 360 /* The type of a function that is used to create a TUI window.  */
 361
 362 typedef std::function<tui_win_info * (const char *name)> window_factory;
 363
 364 /* The type for a data structure that maps a window name to that window's
 365    factory function.  */
 366 typedef std::unordered_map<std::string, window_factory> window_types_map;
 367
 368 /* Register a new TUI window type.  NAME is the name of the window
 369    type.  FACTORY is a function that can be called to instantiate the
 370    window.  */
 371
 372 extern void tui_register_window (const char *name, window_factory &&factory);
 373
 374 /* An iterator class that exposes just the window names from the
 375    known_window_types map in tui-layout.c.  This is just a wrapper around
 376    an iterator of the underlying known_window_types map, but this just
 377    exposes the window names.  */
 378
 379 struct known_window_names_iterator
 380 {
 381   using known_window_types_iterator = window_types_map::iterator;
 382
 383   known_window_names_iterator (known_window_types_iterator &&iter)
 384     : m_iter (std::move (iter))
 385   { /* Nothing.  */ }
 386
 387   known_window_names_iterator &operator++ ()
 388   {
 389     ++m_iter;
 390     return *this;
 391   }
 392
 393   const std::string &operator* () const
 394   { return (*m_iter).first; }
 395
 396   bool operator!= (const known_window_names_iterator &other) const
 397   { return m_iter != other.m_iter; }
 398
 399 private:
 400
 401   /* The underlying iterator.  */
 402   known_window_types_iterator m_iter;
 403 };
 404
 405 /* A range adapter that makes it possible to iterate over the names of all
 406    known tui windows.  */
 407
 408 using known_window_names_range
 409   = iterator_range<known_window_names_iterator>;
 410
 411 /* Return a range that can be used to walk over the name of all known tui
 412    windows in a range-for loop.  */
 413
 414 extern known_window_names_range all_known_window_names ();
 415
 416 #endif /* TUI_TUI_LAYOUT_H */