doc/docsrc/gui.doc

   1 /**
   2
   3 \page gui GUI
   4
   5 As already described in the \ref general section, enigma provides an api for gui functionality.
   6
   7 Let's refine what a widget is:
   8
   9 A widget is a rectangular area on the screen with a content, for example a label, a decorated window, a button
  10 or anything else. Widgets can have child widgets. Child widgets life inside a special area of the parent widget,
  11 inside the clientrect. The clientrect is another rectangular area which is completely inside of the parent widget.
  12 More specific, it's the whole parent widget minus it's borders ("decoration"). For example, the titlebar of a window
  13 isn't belonging to the clientrect, but everything else is.
  14
  15 Say we want to display a message on the screen (and we forget about the fact that enigma provides you a ready-to-use
  16 messagebox). We like to create a window first:
  17
  18 \sa eWidget the generic widget, baseclass for all widgets
  19 \sa eWindow the decorated, toplevel widget
  20
  21 \code
  22 eWindow *window=new eWindow();
  23 \endcode
  24
  25 Now we want to set it to the right position:
  26
  27 \code
  28 window->move(ePoint(100, 100));
  29 window->resize(ePoint(400, 300));
  30 \endcode
  31
  32 Now we want to show it onto the screen since it's hidden by default:
  33
  34 \code
  35 window->show();
  36 \endcode
  37
  38 But we still need to set a title:
  39 \code
  40 window->setText("Hello world!");
  41 \endcode
  42
  43 We might put the \c show at the end if we like to avoid any flickering which occurs otherwise.
  44
  45 But doesn't the widget looks a bit empty? Let's insert some text into it:
  46
  47 \code
  48 eLabel *label=new eLabel(window);
  49 label->setText("foobar");
  50 label->setFont(gFont("NimbusSansL-Regular Sans L Regular", 12));
  51 label->move(ePoint(0, 0));
  52 label->resize(window->getClientRectSize());
  53 \endcode
  54
  55 So we created a label inside the parent, in this case \c window. We set some text and a font.
  56
  57 We still need something to press on, say, a button.
  58
  59 \code
  60 eButton *button=new eButton(window);
  61 button->setText("quit");
  62 button->move(ePoint(50, 50));
  63 button->resize(ePoint(100, 100));
  64 \endcode
  65
  66 But something must happen when we press the button. So we \e connect it. Connections are done using \ref signalslot.
  67 As a summary, \c eButton offers a signal called \c eButton::selected. We simply connect it onto \c accepted here, but
  68 we could use any own function here.
  69
  70 \code
  71 window->CONNECT(button->selected, eWindow::accepted);
  72 \endcode
  73  ------------ dass muss nochmal nachgeguckt werden ------------
  74
  75 Then off we go: Since we want to wait until the user pressed a button, we're making the "dialog" \e modal. Modal means that
  76 the call is synchronous.
  77
  78 \code
  79 ...
  80 window->show();
  81 window->exec();
  82 window->hide();
  83 delete window;
  84 \endcode
  85
  86 \c exec returns when \c eButton::selected is emittet and \c eWindow::accepted is called. \c hide hides the window again.
  87 After that, we destroy the window. Note that all child widgets get destroyed too.
  88
  89 It's perfectly ok to inherit \c eWindow. Normal dialogs are done that way.
  90 For example, a simple dialog looks like this:
  91 \code
  92 class SimpleDLG: public eWindow
  93 {
  94         eButton *b_quit;
  95 public:
  96         SimpleDLG(): eWindow(0)
  97         {
  98                 setText("A simple dialog");
  99                 move(ePoint(100, 100));
 100                 resize(eSize(500, 400));
 101
 102                 b_quit=new eButton(this);
 103                 b_quit->move(ePoint(0, 30));
 104                 b_quit->resize(eSize(clientrect.width(), 30));
 105                 b_quit->setText("ok");
 106                 CONNECT(b_quit->selected, SimpleDLG::accept);
 107         }
 108 };
 109 \endcode
 110
 111 Everything fine? Then jump into the \ref skin section!
 112
 113 */