src/Widget/Widget.hpp

   1 /*
   2 Copyright_License {
   3
   4   XCSoar Glide Computer - http://www.xcsoar.org/
   5   Copyright (C) 2000-2013 The XCSoar Project
   6   A detailed list of copyright holders can be found in the file "AUTHORS".
   7
   8   This program is free software; you can redistribute it and/or
   9   modify it under the terms of the GNU General Public License
  10   as published by the Free Software Foundation; either version 2
  11   of the License, or (at your option) any later version.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18   You should have received a copy of the GNU General Public License
  19   along with this program; if not, write to the Free Software
  20   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  21 }
  22 */
  23
  24 #ifndef XCSOAR_WIDGET_HPP
  25 #define XCSOAR_WIDGET_HPP
  26
  27 #include "Compiler.h"
  28
  29 #include "assert.h"
  30
  31 struct PixelSize;
  32 struct PixelRect;
  33 class ContainerWindow;
  34
  35 /**
  36  * A Widget is an area on the screen that the user can interact with
  37  * or that just shows non-interactive data.  It can be implemented by
  38  * any Window derivative.  The Widget class acts as an adapter with a
  39  * well-defined interface.  It is used to split large forms into
  40  * smaller self-contained parts.  For example, a Widget can represent
  41  * the contents of one tab.
  42  */
  43 class Widget {
  44 public:
  45   /**
  46    * A virtual destructor prototype that allows containers to delete
  47    * Widget pointers.
  48    */
  49   virtual ~Widget();
  50
  51   /**
  52    * Estimate the minimum recommended size.  May return zero if the
  53    * method has no special implementation.  This is called after
  54    * Prepare().
  55    */
  56   gcc_pure
  57   virtual PixelSize GetMinimumSize() const = 0;
  58
  59   /**
  60    * Estimate the maximum recommended size; the Widget may become
  61    * larger, but that is of little use.  May return zero if the method
  62    * has no special implementation.  This is called after
  63    * Prepare().
  64    */
  65   gcc_pure
  66   virtual PixelSize GetMaximumSize() const = 0;
  67
  68   /**
  69    * Called as early as possible after the Widget has been added to
  70    * the container.  If needed, an implementation might decide to
  71    * create the Window here, but it is suggested to postpone it to
  72    * Prepare(), if possible.
  73    */
  74   virtual void Initialise(ContainerWindow &parent, const PixelRect &rc) = 0;
  75
  76   /**
  77    * Called before the Widget is going to be shown for the first time.
  78    * The class should create the Window here, unless it has been
  79    * created already in Initialise().
  80    */
  81   virtual void Prepare(ContainerWindow &parent, const PixelRect &rc) = 0;
  82
  83   /**
  84    * Called before a Widget is going to be deleted.  Unlike the
  85    * destructor, this method will only be called if Prepare() has been
  86    * called previously.
  87    */
  88   virtual void Unprepare() = 0;
  89
  90   /**
  91    * Save data that was modified by the user.  Will only be called if
  92    * Prepare() has been invoked previously.  Although this is likely
  93    * to be called just before destroying the widget, this should not
  94    * modify the widget.
  95    *
  96    * @return true on success, false if saving did not succeed (the
  97    * method should display a message to the user prior to returning)
  98    */
  99   virtual bool Save(bool &changed) = 0;
 100
 101   /**
 102    * The user has clicked on the activation area (within the
 103    * container) of this Widget, which will show the widget.  The
 104    * Widget may now decide to do something else instead.
 105    *
 106    * This may be called before Prepare().
 107    *
 108    * @return true to continue, false to cancel the "Show" operation
 109    */
 110   virtual bool Click() = 0;
 111
 112   /**
 113    * The user has clicked on the activation area while the Widget was
 114    * already visible.
 115    */
 116   virtual void ReClick() = 0;
 117
 118   /**
 119    * Make the widget visible.  This will only be called after
 120    * Prepare(), and will not be called again until Hide() has been
 121    * called.
 122    */
 123   virtual void Show(const PixelRect &rc) = 0;
 124
 125   /**
 126    * Perform operations prior to hiding.
 127    * Shall be called prior to calling Hide().
 128    * The caller can decide whether to call Hide() if Leave() returns
 129    * false.
 130    * @return true if the condition of the widget is in the
 131    * expected state for Hide().  Else false.
 132    */
 133   virtual bool Leave() = 0;
 134
 135   /**
 136    * Make the widget invisible.  This will only be called when it is
 137    * visible already.
 138    */
 139   virtual void Hide() = 0;
 140
 141   /**
 142    * Move the widget.  This will only be called while it is visible.
 143    */
 144   virtual void Move(const PixelRect &rc) = 0;
 145
 146   /**
 147    * Grab keyboard focus.
 148    *
 149    * @return false if the Widget is not interested in keyboard focus
 150    */
 151   virtual bool SetFocus() = 0;
 152 };
 153
 154 /**
 155  * A Widget that implements a few optional methods as no-ops.  Aimed
 156  * to simplify Widget implementations that don't need all methods.
 157  */
 158 class NullWidget : public Widget {
 159 public:
 160   virtual ~NullWidget();
 161
 162   virtual PixelSize GetMinimumSize() const override;
 163   virtual PixelSize GetMaximumSize() const override;
 164   virtual void Initialise(ContainerWindow &parent, const PixelRect &rc)
 165     override;
 166   virtual void Prepare(ContainerWindow &parent, const PixelRect &rc)
 167     override;
 168   virtual void Unprepare() override;
 169   virtual bool Save(bool &changed) override;
 170   virtual bool Click() override;
 171   virtual void ReClick() override;
 172   virtual bool Leave() override;
 173   virtual void Move(const PixelRect &rc) override;
 174   virtual bool SetFocus() override;
 175 };
 176
 177 #endif