include/lib/gui/ewidget.h

   1 #ifndef __ewidget_h
   2 #define __ewidget_h
   3
   4 #include <lib/base/ebase.h>
   5 #include <lib/base/estring.h>
   6 #include <lib/base/epoint.h>
   7 #include <lib/base/esize.h>
   8 #include <lib/base/erect.h>
   9 #include <lib/base/eptrlist.h>
  10 #include <libsig_comp.h>
  11 #include <lib/gdi/grc.h>
  12 #include <lib/driver/rc.h>
  13 #include <lib/gui/actions.h>
  14 #include <lib/gui/decoration.h>
  15 #include <lib/system/econfig.h>
  16
  17 class eWidgetEvent
  18 {
  19 public:
  20         enum eventType
  21         {
  22                 evtKey,
  23                 willShow, willHide,
  24                 execBegin, execDone,
  25                 gotFocus, lostFocus,
  26
  27                 changedText, changedFont, changedForegroundColor, changedBackgroundColor,
  28                 changedSize, changedPosition, changedPixmap, childChangedHelpText,
  29
  30                 evtAction, evtShortcut, wantClose
  31         } type;
  32         union
  33         {
  34                 int parameter;
  35                 const eAction *action;
  36                 const eRCKey *key;
  37         };
  38         eWidgetEvent(eventType type, int parameter=0): type(type), parameter(parameter) { }
  39         eWidgetEvent(eventType type, const eAction *action): type(type), action(action) { }
  40         eWidgetEvent(eventType type, const eRCKey &key): type(type), key(&key) { }
  41
  42         /**
  43          * \brief Event should be delivered to the focused widget.
  44          *
  45          * \return true if the event should be delivered to the focused widget instead of the widget itself.
  46          */
  47         int toFocus() const
  48         {
  49                 switch (type)
  50                 {
  51                 case evtKey:
  52                         return 1;
  53                 default:
  54                         return 0;
  55                 }
  56         }
  57 };
  58
  59 /** \brief The main widget class. All widgets inherit this class.
  60  * eWidget handles focus management.
  61  */
  62 class eWidget: public Object
  63 {
  64         enum
  65         {
  66                 /// Widget was shown with show() or implicit show()
  67                 stateShow=1,
  68                 /// Widget is visible on screen. Implies stateShow.
  69                 stateVisible=2
  70         };
  71
  72 public:
  73         /**
  74          * \brief Exits a (model) widget.
  75          *
  76          * Quit the local event loop, thus returning the control to the function which called \a exec.
  77          * \sa eWidget::accept
  78          * \sa eWidget::reject
  79          */
  80         void close(int result);
  81
  82         /**
  83          * \brief Closes with a returncode of 0 (success).
  84          *
  85          * Synonym to \a close(0);. Useful to use as a slot.
  86          * \sa eWidget::close
  87          */
  88         void accept();
  89
  90         /**
  91          * \brief Closes with a returncode of -1 (failure).
  92          *
  93          * Synonym to \a close(-1);. Useful to use as a slot.
  94          * \sa eWidget::close
  95          */
  96         void reject();
  97         void setActive( bool, eWidget* w=0, bool b=false );
  98         /**
  99          * \brief Signal is send, when the focus Changed
 100          *
 101          * used from a existing statusbar.
 102          * \sa eWidget::focusChanged
 103          */
 104         Signal1<void, const eWidget*> focusChanged;
 105         static Signal2< void, ePtrList<eAction>*, int > showHelp;
 106         static Signal1<void, const eWidget*> globalFocusChanged;
 107 protected:
 108         ePtrList<eAction> actionHelpList;
 109         int helpID;
 110         ePtrList<eWidget> childlist;
 111         static eWidget *root;
 112         eWidget *parent;
 113         eString name;
 114         eString helptext;
 115         ePoint position;
 116         ePoint absPosition;
 117         eSize size;
 118         eRect clientrect;
 119         eRect clientclip;
 120
 121         eAction *shortcut;
 122         eWidget *shortcutFocusWidget;
 123
 124         ePtrList<eWidget> _focusList;
 125
 126         ePtrList<eWidget> actionListener;
 127         eWidget *focus, *TLW;
 128
 129                 /// old top-level focus
 130         eWidget *oldTLfocus;
 131         int takefocus;
 132         int state;
 133
 134         gDC *target;
 135
 136         inline eWidget *getTLW() // pseudoTLW !!
 137         {
 138                 return TLW ? TLW : (TLW = (parent && parent->parent) ? parent->getTLW() : this );
 139         }
 140         int result, in_loop, have_focus, just_showing;
 141         void takeFocus();
 142         void releaseFocus();
 143
 144         void _willShow();
 145         void _willHide();
 146
 147         virtual void willShow();
 148         virtual void willHide();
 149
 150         virtual void setPalette();
 151
 152         void willShowChildren();
 153         void willHideChildren();
 154
 155         /**
 156          * \brief Hi priority event filter.
 157          *
 158          * This event filter is called before the event is delivered via \a event.
 159          * \return 1 if the event should NOT be forwarded.
 160          */
 161         virtual int eventFilter(const eWidgetEvent &event);
 162
 163         /**
 164          * \brief Handles an event.
 165          *
 166          * If re-implemented in a widget-sub-class, \c eWidget::event should be called whenever the event is
 167          * not processed by the widget.
 168          * \return 1 if the event was processed, 0 if ignored. it might be forwarded to other widgets then.
 169          */
 170
 171         virtual int keyDown(int rc);
 172         virtual int keyUp(int rc);
 173
 174         virtual void gotFocus();
 175         virtual void lostFocus();
 176
 177         virtual void recalcClientRect();
 178         void recalcClip();
 179         void checkFocus();
 180
 181         typedef ePtrList<eActionMap> actionMapList;
 182
 183         void findAction(eActionPrioritySet &prio, const eRCKey &key, eWidget *context);
 184         void addActionMap(eActionMap *map);
 185         void removeActionMap(eActionMap *map);
 186         actionMapList actionmaps;
 187         static actionMapList globalActions;
 188
 189                         // generic properties
 190         gFont font;
 191         eString text;
 192         gColor backgroundColor, foregroundColor;
 193
 194         gPixmap *pixmap;
 195
 196         eString descr;
 197
 198 public:
 199         virtual int eventHandler(const eWidgetEvent &event);
 200         static void addGlobalActionMap(eActionMap *map);
 201         static void removeGlobalActionMap(eActionMap *map);
 202         inline eWidget *getNonTransparentBackground()
 203         {
 204                 if (backgroundColor >= 0)
 205                         return this;
 206                 return parent?parent->getNonTransparentBackground():this;
 207         }
 208
 209 //#ifndef DISABLE_LCD
 210         eWidget *LCDTitle;
 211         eWidget *LCDElement;
 212         eWidget *LCDTmp;
 213 //#endif
 214
 215         void recalcAbsolutePosition();
 216
 217         inline const ePoint &getAbsolutePosition() const
 218         {
 219                 return absPosition;
 220         }
 221
 222         inline ePoint getRelativePosition(eWidget *e) const
 223         {
 224                 ePoint pos=position;
 225                 if (this != e)
 226                         for (eWidget *a=parent; a && (a != e); a=a->parent)
 227                                 pos+=a->clientrect.topLeft();
 228                 return pos;
 229         }
 230
 231         virtual void redrawWidget(gPainter *target, const eRect &area);
 232
 233         virtual void eraseBackground(gPainter *target, const eRect &area);
 234
 235         /**
 236          * \brief Constructs a new eWidget.
 237          * \param parent The parent widget. The widget gets automatically removed when the parent gets removed.
 238          * \param takefocus Specifies if the widget should be appended to the focus list of the TLW, i.e. if it can
 239                   receive keys.
 240          */
 241         eWidget(eWidget *parent=0, int takefocus=0);
 242
 243         /**
 244          * \brief Destructs an eWidget and all its childs.
 245          *
 246          * hide() is called when the widget is shown. The set ePixmap is \e not
 247          * freed. If the widget acquired focus, it will be removed from the focuslist.
 248          * \sa eWidget::setPixmap
 249          */
 250         virtual ~eWidget();
 251
 252         /**
 253          * \brief Returns a pointer to the focus list.
 254          *
 255          * The focus list is the list of childs which have the \c takefocus flag set.
 256          * This list is only maintained for TLWs.
 257          */
 258         ePtrList<eWidget> *focusList() { return &_focusList; }
 259
 260         /**
 261          * \brief Resizes the widget.
 262          *
 263          * Sets the size of the widget to the given size. The event \c changedSize event will be generated.
 264          * \param size The new size, relative to the position.
 265          */
 266         void resize(const eSize& size);
 267
 268         /**
 269          * \brief Resizes clientrect (and the widget).
 270          *
 271          * Sets the clientrect of the widget to the given size. The real size of the widget will be set to met
 272          * these requirement. The event \c changedSize event will be generated.
 273          * \param size The new size of the clientrect, relative to the position.
 274          */
 275         void cresize(const eSize& size);
 276
 277         /**
 278          * \brief Moves the widget.
 279          *
 280          * Set the new position of the widget to the given position. The \c changedPosition event will be generated.
 281          * \param position The new position, relative to the parent's \c clientrect.
 282          */
 283         void move(const ePoint& position);
 284
 285         /**
 286          * \brief Moves the clientrect (and the widget).
 287          *
 288          * Set the new position of the clientrect to the given position. The \c changedPosition event will be generated.
 289          * \param position The new position, relative to the parent's \c clientrect.
 290          */
 291         void cmove(const ePoint& position);
 292
 293          /**
 294          * \brief vertically align the widget.
 295          *
 296          * Set the new vertical align position of the widget to center of the screen
 297          */
 298
 299         void valign();
 300
 301         /**
 302          * \brief Returns the current size.
 303          *
 304          * \return Current size of the widget, relative to the position.
 305          */
 306         const eSize& getSize() const { return size; }
 307
 308         /**
 309          * \brief Returns the current position.
 310          *
 311          * \return Current position, relative to the parent's \c clientrect.
 312          */
 313         const ePoint& getPosition() const { return position; }
 314
 315         /**
 316          * \brief Returns the size of the clientrect.
 317          *
 318          * \return The usable size for the childwidgets.
 319          */
 320         eSize getClientSize() const { return clientrect.size(); }
 321
 322         /**
 323          * \brief Returns the clientrect.
 324          *
 325          * \return The area usable for the childwidgets.
 326          */
 327         const eRect& getClientRect() const { return clientrect; }
 328
 329         /**
 330          * \brief Recursive redraw of a widget.
 331          *
 332          * All client windows get repaint too, but no widgets above. Unless you have a good reason, you shouldn't
 333          * use this function and use \c invalidate().
 334          * \param area The area which should be repaint. The default is to repaint the whole widget.
 335          * \sa eWidget::invalidate
 336          */
 337         void redraw(eRect area=eRect());
 338
 339         /**
 340          * \brief Recursive (complete) redraw of a widget.
 341          *
 342          * Redraws the widget including background. This is the function to use if you want to manually redraw something!
 343          * \param area The area which should be repaint. The default is to repaint the whole widget.
 344          * \param force Forces a parent-invalidate even on non-visible widgets. Shouldn't be used outside eWidget.
 345          * \sa eWidget::redraw
 346          */
 347         void invalidate(eRect area=eRect(), int force=0);
 348
 349         /**
 350          * \brief Enters modal message loop.
 351          *
 352          * A new event loop will be launched. The function returns when \a close is called.
 353          * \return The argument of \a close.
 354          * \sa eWidget::close
 355          */
 356         int exec();
 357
 358         /**
 359          * \brief Visually clears the widget.
 360          *
 361          * Clears the widget. This is done on \a hide().
 362          * \sa eWidget::hide
 363          */
 364         void clear();
 365
 366         /**
 367          * \brief Delivers a widget-event.
 368          *
 369          * Internally calles \a eventFilter, then \a eventHandler() (in some cases of the focused widget)
 370          * \param event The event to deliver.
 371          */
 372         int event(const eWidgetEvent &event);
 373
 374         /**
 375          * \brief Shows the widget.
 376          *
 377          * If necessary, the widget will be linked into the TLW's active focus list. The widget will
 378          * visually appear.
 379          * \sa eWidget::hide
 380          */
 381         void show();
 382
 383         /**
 384          * \brief Hides the widget.
 385          *
 386          * The widget will be removed from the screen. All childs will be hidden too.
 387          * \sa eWidget::show
 388          */
 389         void hide();
 390
 391         /**
 392          * \brief Returns if the widget is vissible.
 393          *
 394          * \return If the widget and all parents are visible, \c true is returned, else false.
 395          */
 396         int isVisible() {               return (state&stateVisible) && ( (!parent) || parent->isVisible() );    }
 397
 398         /**
 399          * \brief Possible focus directions.
 400          */
 401         enum focusDirection
 402         {
 403                 focusDirNext, focusDirPrev, focusDirN, focusDirE, focusDirS, focusDirW
 404         };
 405
 406         /**
 407          * \brief changes the focused widget.
 408          *
 409          * Focuses the next or previous widget of the \c focuslist. An \c gotFocus and \c lostFocus event will be
 410          * generated.
 411          * \param dir The direction, \c focusDirection.
 412          */
 413         void focusNext(int dir=0);
 414
 415         /**
 416          * \brief Gives focus to a widget.
 417          *
 418          * Set the focus to the specified widget. The \c focuslist is updated, too.
 419          * An \c gotFocus and \c lostFocus event will be generated.
 420          * \param newfocus The new widget to focus.
 421          */
 422         void setFocus(eWidget *newfocus);
 423
 424         /**
 425          * \brief Sets the widget font.
 426          *
 427          * The font is used for example by the \c eLabel.
 428          * \sa eLabel
 429          * \param font The new font used by widget-specific drawing code.
 430          */
 431         void setFont(const gFont &font);
 432
 433         /**
 434          * \brief Sets the widget caption or text.
 435          *
 436          * \param label The text to assign to the widget.
 437          */
 438         void setText(const eString &label);
 439
 440         const eString& getText() const { return text; }
 441         void setBackgroundColor(const gColor& color, bool inv=true);
 442         void setForegroundColor(const gColor& color, bool inv=true);
 443         void setPixmap(gPixmap *pmap);
 444         void setTarget(gDC *target);
 445         gDC *getTarget() { return target; }
 446
 447 #ifndef DISABLE_LCD
 448         void setLCD(eWidget *lcdtitle, eWidget *lcdelement);
 449 #endif
 450
 451         void setName(const char *name);
 452         const eString& getName() const { return name; }
 453         eWidget*& getParent() { return parent; }
 454         const gFont& getFont() const { return font; }
 455
 456         const gColor& getBackgroundColor() const { return backgroundColor; }
 457         const gColor& getForegroundColor() const { return foregroundColor; }
 458
 459         int width() { return getSize().width(); }
 460         int height() { return getSize().height(); }
 461
 462         gPainter *getPainter(eRect area);
 463
 464         const eString& getHelpText() const      {       return helptext;        }
 465
 466         void setHelpText( const eString&);
 467         /**
 468          * \brief Sets a property.
 469          *
 470          * A property is a value/data pair which is used for serializing widgets (like in skinfiles).
 471          * These properties are available to all \c "eWidget"-based classes.
 472          * \arg \c position, the position of the widget, relative to the parent's childarea. Consider using csize for TLWs.
 473          * Positions are specified in a "x:y" manner.
 474          * \arg \c cposition, the position of the widget's clientrect (upper left).
 475          * This is useful for specifing a position independant of a decoration which might be
 476          * different sized. The real position will be calculated to match the requested position.
 477          * \arg \c size, the size of the widget. Consider using csize for TLWs. Sizes are specified in a "width:height" manner.
 478          * \arg \c csize, the size of the clientrect. The real size will be calculated to match the requested size.
 479          * \arg \c text, the text/caption of the widget.
 480          * \arg \c font, the primary font used in the widget.
 481          * \arg \c name, the name of the widget for referring them.
 482          * \arg \c pixmap, an already loaded, named pixmap to be used as the widget's pixmap.
 483          * \arg \c foregroundColor, a named color, which will be used for the widget's foreground color.
 484          * \arg \c backgroundColor
 485          * \param prop The property to be set.
 486          * \param value The value to be set.
 487          */
 488         virtual int setProperty(const eString &prop, const eString &value);
 489
 490         eWidget *search(const eString &name);
 491
 492         eWidget* getFocus() { return focus; }
 493
 494         void makeRoot();
 495
 496         void zOrderLower();
 497         void zOrderRaise();
 498
 499         /**
 500          * \brief sets the shortcut (generate evtShortcut)
 501          */
 502         void setShortcut(const eString &shortcut);
 503         void setShortcutFocus(eWidget *focus);
 504
 505         void addActionToHelpList(eAction *action);
 506         void clearHelpList();
 507         void setHelpID(int fHelpID);
 508 };
 509
 510 class eDecoWidget:public eWidget
 511 {
 512 protected:
 513         eString strDeco;
 514         eRect crect, crect_selected;
 515         eDecoration deco, deco_selected;
 516         int setProperty( const eString &prop, const eString &value);
 517         int eventFilter( const eWidgetEvent &evt);
 518 public:
 519         void setDeco( const char* deco )
 520         {
 521                 strDeco = deco;
 522         }
 523         void loadDeco();
 524         eDecoWidget( eWidget* parent=0, int takefocus=0, const char* deco="" )
 525         :eWidget(parent, takefocus), strDeco( deco )
 526         {       }
 527         const eDecoration& getDeco()    { return deco; }
 528         const eDecoration& getDecoSelected()    { return deco_selected; }
 529 };
 530
 531 #endif