src/window.h

   1 /***************************************************************************
   2  *   Copyright (C) 2008-2009 by Andrzej Rybczak                            *
   3  *   electricityispower@gmail.com                                          *
   4  *                                                                         *
   5  *   This program is free software; you can redistribute it and/or modify  *
   6  *   it under the terms of the GNU General Public License as published by  *
   7  *   the Free Software Foundation; either version 2 of the License, or     *
   8  *   (at your option) any later version.                                   *
   9  *                                                                         *
  10  *   This program is distributed in the hope that it will be useful,       *
  11  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  12  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
  13  *   GNU General Public License for more details.                          *
  14  *                                                                         *
  15  *   You should have received a copy of the GNU General Public License     *
  16  *   along with this program; if not, write to the                         *
  17  *   Free Software Foundation, Inc.,                                       *
  18  *   51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.              *
  19  ***************************************************************************/
  20
  21 #ifndef _WINDOW_H
  22 #define _WINDOW_H
  23
  24 #ifdef HAVE_CONFIG_H
  25 #include <config.h>
  26 #endif
  27
  28 #ifdef USE_PDCURSES
  29 # define NCURSES_MOUSE_VERSION 1
  30 #endif
  31
  32 #include "curses.h"
  33
  34 #include <deque>
  35 #include <stack>
  36 #include <vector>
  37 #include <string>
  38
  39 #if defined(__GNUC__) && __GNUC__ >= 3
  40 # define GNUC_UNUSED __attribute__((unused))
  41 # define GNUC_PRINTF(a, b) __attribute__((format(printf, a, b)))
  42 #else
  43 # define GNUC_UNUSED
  44 # define GNUC_PRINTF(a, b)
  45 #endif
  46
  47 #ifdef USE_PDCURSES
  48 # undef KEY_BACKSPACE
  49 # define KEY_BACKSPACE 8
  50 #else
  51 // NOTICE: redefine BUTTON2_PRESSED as it doesn't always work, I noticed
  52 // that it sometimes returns 134217728 instead of expected mask, so the
  53 // modified define does it right but is rather experimental.
  54 # undef BUTTON2_PRESSED
  55 # define BUTTON2_PRESSED (NCURSES_MOUSE_MASK(2, NCURSES_BUTTON_PRESSED) | 134217728U)
  56 #endif // USE_PDCURSES
  57
  58 #ifdef _UTF8
  59 # define my_char_t wchar_t
  60 # define U(x) L##x
  61 # define TO_STRING(x) ToString(x)
  62 # define TO_WSTRING(x) ToWString(x)
  63 #else
  64 # define my_char_t char
  65 # define U(x) x
  66 # define TO_STRING(x) (x)
  67 # define TO_WSTRING(x) (x)
  68 #endif
  69
  70 // workaraund for win32
  71 #ifdef WIN32
  72 # define wcwidth(x) 1
  73 #endif
  74
  75 /// Converts wide string to narrow string
  76 /// @param ws wide string
  77 /// @return narrow string
  78 ///
  79 std::string ToString(const std::wstring &ws);
  80
  81 /// Converts narrow string to wide string
  82 /// @param s narrow string
  83 /// @return wide string
  84 ///
  85 std::wstring ToWString(const std::string &s);
  86
  87 /// NCurses namespace provides set of easy-to-use
  88 /// wrappers over original curses library
  89 ///
  90 namespace NCurses
  91 {
  92         /// Colors used by NCurses
  93         ///
  94         enum Color { clDefault, clBlack, clRed, clGreen, clYellow, clBlue, clMagenta, clCyan, clWhite, clEnd };
  95
  96         /// Format flags used by NCurses
  97         ///
  98         enum Format {
  99                 fmtNone = clEnd+1,
 100                 fmtBold, fmtBoldEnd,
 101                 fmtUnderline, fmtUnderlineEnd,
 102                 fmtReverse, fmtReverseEnd,
 103                 fmtAltCharset, fmtAltCharsetEnd
 104         };
 105
 106         /// Available border colors for window
 107         ///
 108         enum Border { brNone, brBlack, brRed, brGreen, brYellow, brBlue, brMagenta, brCyan, brWhite };
 109
 110         /// This indicates how much the window has to be scrolled
 111         ///
 112         enum Where { wUp, wDown, wPageUp, wPageDown, wHome, wEnd };
 113
 114         /// Helper function that is invoked each time one will want
 115         /// to obtain string from Window::GetString() function
 116         /// @see Window::GetString()
 117         ///
 118         typedef void (*GetStringHelper)(const std::wstring &);
 119
 120         /// Initializes curses screen and sets some additional attributes
 121         /// @param window_title title of the window (has an effect only if pdcurses lib is used)
 122         /// @param enable_colors enables colors
 123         ///
 124         void InitScreen(const char *window_title, bool enable_colors);
 125
 126         /// Destroys the screen
 127         ///
 128         void DestroyScreen();
 129
 130         /// Struct used to set color of both foreground and background of window
 131         /// @see Window::operator<<()
 132         ///
 133         struct Colors
 134         {
 135                 Colors(Color one, Color two = clDefault) : fg(one), bg(two) { }
 136                 Color fg;
 137                 Color bg;
 138         };
 139
 140         /// Struct used for going to given coordinates
 141         /// @see Window::operator<<()
 142         ///
 143         struct XY
 144         {
 145                 XY(int xx, int yy) : x(xx), y(yy) { }
 146                 int x;
 147                 int y;
 148         };
 149
 150         /// Main class of NCurses namespace, used as base for other specialized windows
 151         ///
 152         class Window
 153         {
 154                 public:
 155                         /// Constructs an empty window with given parameters
 156                         /// @param startx X position of left upper corner of constructed window
 157                         /// @param starty Y position of left upper corner of constructed window
 158                         /// @param width width of constructed window
 159                         /// @param height height of constructed window
 160                         /// @param title title of constructed window
 161                         /// @param color base color of constructed window
 162                         /// @param border border of constructed window
 163                         ///
 164                         Window(size_t startx, size_t starty, size_t width, size_t height,
 165                                const std::string &title, Color color, Border border);
 166
 167                         /// Copies thw window
 168                         /// @param w copied window
 169                         ///
 170                         Window(const Window &w);
 171
 172                         /// Destroys the window and frees memory
 173                         ///
 174                         virtual ~Window();
 175
 176                         /// Allows for direct access to internal WINDOW pointer in case there
 177                         /// is no wrapper for a function from curses library one may want to use
 178                         /// @return internal WINDOW pointer
 179                         ///
 180                         WINDOW *Raw() const { return itsWindow; }
 181
 182                         /// @return window's width
 183                         ///
 184                         size_t GetWidth() const;
 185
 186                         /// @return window's height
 187                         ///
 188                         size_t GetHeight() const;
 189
 190                         /// @return X position of left upper window's corner
 191                         ///
 192                         size_t GetStartX() const;
 193
 194                         /// @return Y position of left upper window's corner
 195                         ///
 196                         size_t GetStartY() const;
 197
 198                         /// @return window's title
 199                         ///
 200                         const std::string &GetTitle() const;
 201
 202                         /// @return current window's color
 203                         ///
 204                         Color GetColor() const;
 205
 206                         /// @return current window's border
 207                         ///
 208                         Border GetBorder() const;
 209
 210                         /// Reads the string from standard input. Note that this is much more complex
 211                         /// function than getstr() from curses library. It allows for moving through
 212                         /// letters with arrows, supports scrolling if string's length is bigger than
 213                         /// given area, supports history of previous strings and each time it receives
 214                         /// an input from the keyboard or the timeout is reached, it calls helper function
 215                         /// (if it's set) that takes as an argument currently edited string.
 216                         /// @param base base string that has to be edited
 217                         /// @param length max length of string, unlimited by default
 218                         /// @param width width of area that entry field can take. if it's reached, string
 219                         /// will be scrolled. if value is 0, field will be from cursor position to the end
 220                         /// of current line wide.
 221                         /// @param encrypted if set to true, '*' characters will be displayed instead of
 222                         /// actual text.
 223                         /// @return edited string
 224                         ///
 225                         /// @see SetGetStringHelper()
 226                         /// @see SetTimeout()
 227                         /// @see CreateHistory()
 228                         ///
 229                         std::string GetString(const std::string &base, size_t length = -1,
 230                                               size_t width = 0, bool encrypted = 0) const;
 231
 232                         /// Wrapper for above function that doesn't take base string (it will be empty).
 233                         /// Taken parameters are the same as for above.
 234                         ///
 235                         std::string GetString(size_t length = -1, size_t width = 0, bool encrypted = 0) const
 236                         {
 237                                 return GetString("", length, width, encrypted);
 238                         }
 239
 240                         /// Gets present position of cursor's coordinates
 241                         /// @param x variable that will be set to current X position
 242                         /// @param y variable that will be set to current Y position
 243                         ///
 244                         void GetXY(int &x, int &y);
 245
 246                         /// Moves cursor to given coordinates
 247                         /// @param x given X position
 248                         /// @param y given Y position
 249                         ///
 250                         void GotoXY(int x, int y);
 251
 252                         /// @return last X position that was set with GetXY(). Note that it most
 253                         /// likely won't report correct position unless called after GetXY() and
 254                         /// before any function that can print anything to window.
 255                         /// @see GetXY()
 256                         ///
 257                         int X() const;
 258
 259                         /// @return last Y position that was set with GetXY(). Since Y position
 260                         /// doesn't change so frequently as X does, it can be called (with some
 261                         /// caution) after something was printed to window and still may report
 262                         /// correct position, but if you're not sure, obtain Y pos with GetXY()
 263                         /// instead.
 264                         /// @see GetXY()
 265                         ///
 266                         int Y() const;
 267
 268                         /// Used to indicate whether given coordinates of main screen lies within
 269                         /// window area or not and if they do, transform them into in-window coords.
 270                         /// Otherwise function doesn't modify its arguments.
 271                         /// @param x X position of main screen to be checked
 272                         /// @param y Y position of main screen to be checked
 273                         /// @return true if it transformed variables, false otherwise
 274                         ///
 275                         bool hasCoords(int &x, int &y);
 276
 277                         /// Sets helper function used in GetString()
 278                         /// @param helper pointer to function that matches GetStringHelper prototype
 279                         /// @see GetString()
 280                         ///
 281                         void SetGetStringHelper(GetStringHelper helper) { itsGetStringHelper = helper; }
 282
 283                         /// Sets window's base color
 284                         /// @param fg foregound base color
 285                         /// @param bg background base color
 286                         ///
 287                         void SetBaseColor(Color fg, Color bg = clDefault);
 288
 289                         /// Sets window's border
 290                         /// @param border new window's border
 291                         ///
 292                         void SetBorder(Border border);
 293
 294                         /// Sets window's timeout
 295                         /// @param timeout window's timeout
 296                         ///
 297                         void SetTimeout(int timeout);
 298
 299                         /// Sets window's title
 300                         /// @param new_title new title for window
 301                         ///
 302                         void SetTitle(const std::string &new_title);
 303
 304                         /// Creates internal container that stores all previous
 305                         /// strings that were edited using this window.
 306                         ///
 307                         void CreateHistory();
 308
 309                         /// Deletes container with all previous history entries
 310                         ///
 311                         void DeleteHistory();
 312
 313                         /// "Hides" the window by filling its area with given character
 314                         /// @param ch character to fill the area
 315                         /// @see Clear()
 316                         ///
 317                         void Hide(char ch = 32) const;
 318
 319                         /// Refreshed whole window and its border
 320                         /// @see Refresh()
 321                         ///
 322                         void Display();
 323
 324                         /// Refreshes whole window, but not the border
 325                         /// @see Display()
 326                         ///
 327                         virtual void Refresh();
 328
 329                         /// Moves the window to new coordinates
 330                         /// @param new_x new X position of left upper corner of window
 331                         /// @param new_y new Y position of left upper corner of window
 332                         ///
 333                         virtual void MoveTo(size_t new_x, size_t new_y);
 334
 335                         /// Resizes the window
 336                         /// @param new_width new window's width
 337                         /// @param new_height new window's height
 338                         ///
 339                         virtual void Resize(size_t new_width, size_t new_height);
 340
 341                         /// Cleares the window
 342                         /// @param refresh indicates whether window has to be refreshed immediately or not
 343                         ///
 344                         virtual void Clear(bool refresh = 1);
 345
 346                         /// Reads key from standard input and writes it into read_key variable
 347                         /// @param read_key variable for read key to be written into it
 348                         ///
 349                         void ReadKey(int &read_key) const;
 350
 351                         /// Waits until user press a key.
 352                         ///
 353                         void ReadKey() const;
 354
 355                         /// Scrolls the window by amount of lines given in its parameter
 356                         /// @param where indicates how many lines it has to scroll
 357                         ///
 358                         virtual void Scroll(Where where);
 359
 360                         /// Applies function of compatible prototype to internal WINDOW pointer
 361                         /// The mostly used function in this case seem to be wclrtoeol(), which
 362                         /// clears the window from current cursor position to the end of line.
 363                         /// Note that delwin() also matches that prototype, but I wouldn't
 364                         /// recommend anyone passing this pointer here ;)
 365                         /// @param f pointer to function to call with internal WINDOW pointer
 366                         /// @return reference to itself
 367                         ///
 368                         Window &operator<<(int (*f)(WINDOW *));
 369
 370                         /// Applies foreground and background colors to window
 371                         /// @param colors struct that holds new colors information
 372                         /// @return reference to itself
 373                         ///
 374                         Window &operator<<(Colors colors);
 375
 376                         /// Applies foregound color to window. Note that colors applied
 377                         /// that way are stacked, i.e if you applied clRed, then clGreen
 378                         /// and clEnd, current color would be clRed. If you want to discard
 379                         /// all colors and fall back to base one, pass clDefault.
 380                         /// @param color new color value
 381                         /// @return reference to itself
 382                         ///
 383                         Window &operator<<(Color color);
 384
 385                         /// Applies format flag to window. Note that these attributes are
 386                         /// also stacked, so if you applied fmtBold twice, to get rid of
 387                         /// it you have to pass fmtBoldEnd also twice.
 388                         /// @param format format flag
 389                         /// @return reference to itself
 390                         ///
 391                         Window &operator<<(Format format);
 392
 393                         /// Moves current cursor position to given coordinates.
 394                         /// @param coords struct that holds information about new coordinations
 395                         /// @return reference to itself
 396                         ///
 397                         Window &operator<<(XY coords);
 398
 399                         /// Prints string to window
 400                         /// @param s const pointer to char array to be printed
 401                         /// @return reference to itself
 402                         ///
 403                         Window &operator<<(const char *s);
 404
 405                         /// Prints single character to window
 406                         /// @param c character to be printed
 407                         /// @return reference to itself
 408                         ///
 409                         Window &operator<<(char c);
 410
 411                         /// Prints wide string to window
 412                         /// @param ws const pointer to wchar_t array to be printed
 413                         /// @return reference to itself
 414                         ///
 415                         Window &operator<<(const wchar_t *ws);
 416
 417                         /// Prints single wide character to window
 418                         /// @param wc wide character to be printed
 419                         /// @return reference to itself
 420                         ///
 421                         Window &operator<<(wchar_t wc);
 422
 423                         /// Prints int to window
 424                         /// @param i integer value to be printed
 425                         /// @return reference to itself
 426                         ///
 427                         Window &operator<<(int i);
 428
 429                         /// Prints double to window
 430                         /// @param d double value to be printed
 431                         /// @return reference to itself
 432                         ///
 433                         Window &operator<<(double d);
 434
 435                         /// Prints size_t to window
 436                         /// @param s size value to be printed
 437                         /// @return reference to itself
 438                         ///
 439                         Window &operator<<(size_t s);
 440
 441                         /// Prints std::string to window
 442                         /// @param s string to be printed
 443                         /// @return reference to itself
 444                         ///
 445                         Window &operator<<(const std::string &s);
 446
 447                         /// Prints std::wstring to window
 448                         /// @param ws wide string to be printed
 449                         /// @return reference to itself
 450                         ///
 451                         Window &operator<<(const std::wstring &ws);
 452
 453                         /// Fallback for Length() for wide strings used if unicode support is disabled
 454                         /// @param s string that real length has to be measured
 455                         /// @return standard std::string::length() result since it's only fallback
 456                         ///
 457                         static size_t Length(const std::string &s) { return s.length(); }
 458
 459                         /// Measures real length of wide string (required if e.g. asian characters are used)
 460                         /// @param ws wide string that real length has to be measured
 461                         /// @return real length of wide string
 462                         ///
 463                         static size_t Length(const std::wstring &ws);
 464
 465                 protected:
 466                         /// Sets colors of window (interal use only)
 467                         /// @param fg foregound color
 468                         /// @param bg background color
 469                         ///
 470                         void SetColor(Color fg, Color bg = clDefault);
 471
 472                         /// Refreshes window's border
 473                         ///
 474                         void ShowBorder() const;
 475
 476                         /// Changes dimensions of window, called from Resize()
 477                         /// @param width new window's width
 478                         /// @param height new window's height
 479                         /// @see Resize()
 480                         ///
 481                         void AdjustDimensions(size_t width, size_t height);
 482
 483                         /// Deletes old window and creates new. It's called by Resize(),
 484                         /// SetBorder() or SetTitle() since internally windows are
 485                         /// handled as curses pads and change in size requires to delete
 486                         /// them and create again, there is no way to change size of pad.
 487                         /// @see SetBorder()
 488                         /// @see SetTitle()
 489                         /// @see Resize()
 490                         ///
 491                         virtual void Recreate(size_t width, size_t height);
 492
 493                         /// internal WINDOW pointers
 494                         WINDOW *itsWindow;
 495                         WINDOW *itsWinBorder;
 496
 497                         /// start points and dimensions
 498                         size_t itsStartX;
 499                         size_t itsStartY;
 500                         size_t itsWidth;
 501                         size_t itsHeight;
 502
 503                         /// window timeout
 504                         int itsWindowTimeout;
 505
 506                         /// current colors
 507                         Color itsColor;
 508                         Color itsBgColor;
 509
 510                         /// base colors
 511                         Color itsBaseColor;
 512                         Color itsBaseBgColor;
 513
 514                         /// current border
 515                         Border itsBorder;
 516
 517                 private:
 518                         /// Sets state of bold attribute (internal use only)
 519                         /// @param bold_state state of bold attribute
 520                         ///
 521                         void Bold(bool bold_state) const;
 522
 523                         /// Sets state of underline attribute (internal use only)
 524                         /// @param underline_state state of underline attribute
 525                         ///
 526                         void Underline(bool underline_state) const;
 527
 528                         /// Sets state of reverse attribute (internal use only)
 529                         /// @param reverse_state state of reverse attribute
 530                         ///
 531                         void Reverse(bool reverse_state) const;
 532
 533                         /// Sets state of altcharset attribute (internal use only)
 534                         /// @param altcharset_state state of altcharset attribute
 535                         ///
 536                         void AltCharset(bool altcharset_state) const;
 537
 538                         /// pointer to helper function used by GetString()
 539                         /// @see GetString()
 540                         ///
 541                         GetStringHelper itsGetStringHelper;
 542
 543                         /// temporary coordinates
 544                         /// @see X()
 545                         /// @see Y()
 546                         ///
 547                         int itsX;
 548                         int itsY;
 549
 550                         /// window's title
 551                         std::string itsTitle;
 552
 553                         /// stack of colors
 554                         std::stack<Colors> itsColors;
 555
 556                         /// pointer to container used as history
 557                         std::deque<std::wstring> *itsHistory;
 558
 559                         /// counters for format flags
 560                         int itsBoldCounter;
 561                         int itsUnderlineCounter;
 562                         int itsReverseCounter;
 563                         int itsAltCharsetCounter;
 564         };
 565 }
 566
 567 #endif