libcommon|Menu: Added a generic "focused item help" mechanism to the …

…game menu

Handling this using a custom page drawer is clunky to say the least,
as it means one cannot programmatically set up help info at runtime.

A menu::Widget may now be attributed with textual help info that is
automatically drawn when the widget is focused.

Plus some further cleanup.

doomsday/plugins/common/include/hu_lib.h

@@ -167,7 +167,6 @@ struct Widget
     };
 
 public:
-    int _group;        ///< Object group identifier.
     int _flags;        ///< @ref menuObjectFlags.
 
     /// Used with the fixed layout method for positioning this object in
@@ -194,13 +193,13 @@ struct Widget
     int data2;
 
     Rect *_geometry;   ///< Current geometry.
-    Page *_page;  ///< MenuPage which owns this object (if any).
+    Page *_page;       ///< MenuPage which owns this object (if any).
 
     int timer;
 
 public:
     Widget();
-    virtual ~Widget() {}
+    virtual ~Widget();
 
     DENG2_AS_IS_METHODS()
 
@@ -271,8 +270,10 @@ struct Widget
     Widget &setFixedX(int x);
     Widget &setFixedY(int y);
 
-    int shortcut();
+    int group() const;
+    Widget &setGroup(int newGroup);
 
+    int shortcut();
     Widget &setShortcut(int ddkey);
 
     /// @return  Index of the color used from the owning/active page.
@@ -281,8 +282,6 @@ struct Widget
     /// @return  Index of the font used from the owning/active page.
     int font();
 
-    dd_bool isGroupMember(int group) const;
-
     /// @return  @c true if this object has a registered executeable action
     /// associated with the unique identifier @a action.
     dd_bool hasAction(mn_actionid_t action);
@@ -300,6 +299,13 @@ struct Widget
      * @return  Return value of the executed action else @c -1 if NOP.
      */
     int execAction(mn_actionid_t action, void *parameters);
+
+    de::String const &helpInfo() const;
+    Widget &setHelpInfo(de::String newHelpInfo);
+    inline bool hasHelpInfo() const { return !helpInfo().isEmpty(); }
+
+private:
+    DENG2_PRIVATE(d)
 };
 
 int Widget_DefaultCommandResponder(Widget *wi, menucommand_e command);

doomsday/plugins/common/include/hu_menu.h

@@ -131,9 +131,9 @@ de::String Hu_MenuFindPageName(menu::Page const *page);
  */
 menu::Page *Hu_MenuNewPage(char const *name, Point2Raw const *origin, int flags,
     void (*ticker) (menu::Page *page),
-    void (*drawer) (menu::Page *page, Point2Raw const *origin),
-    int (*cmdResponder) (menu::Page *page, menucommand_e cmd),
-    void *userData);
+    void (*drawer) (menu::Page *page, Point2Raw const *origin) = 0,
+    int (*cmdResponder) (menu::Page *page, menucommand_e cmd) = 0,
+    void *userData = 0);
 
 /**
  * This is the main menu drawing routine (called every tic by the drawing

doomsday/plugins/common/src/hu_lib.cpp

@@ -829,8 +829,8 @@ void Page::applyPageLayout()
         if(ob->is<LabelWidget>() && nextOb)
         {
             if(MNObject_IsDrawable(nextOb) &&
-               (nextOb->is<ButtonWidget>()     ||
-                nextOb->is<InlineListWidget>() ||
+               (nextOb->is<ButtonWidget>()         ||
+                nextOb->is<InlineListWidget>()     ||
                 nextOb->is<ColorPreviewWidget>()   ||
                 nextOb->is<InputBindingWidget>()   ||
                 nextOb->is<TextualSliderWidget>()))
@@ -846,7 +846,7 @@ void Page::applyPageLayout()
                 Rect_UniteRaw(geometry, &united);
 
                 // Extra spacing between object groups.
-                if(i + 2 < _widgets.count() && nextOb->_group != _widgets[i + 2]->_group)
+                if(i + 2 < _widgets.count() && nextOb->group() != _widgets[i + 2]->group())
                 {
                     origin.y += lh;
                 }
@@ -862,8 +862,10 @@ void Page::applyPageLayout()
         origin.y += Rect_Height(ob->_geometry) + lineOffset;
 
         // Extra spacing between object groups.
-        if(nextOb && nextOb->_group != ob->_group)
+        if(nextOb && nextOb->group() != ob->group())
+        {
             origin.y += lh;
+        }
 
         // Proceed to the next object!
         i += 1;
@@ -1067,6 +1069,13 @@ void MN_DrawPage(Page *page, float alpha, dd_bool showFocusCursor)
         page->drawer(page, &page->origin);
         FR_PopAttrib();
     }
+
+    // How about some additional help/information for the focused item?
+    if(focusObj && focusObj->hasHelpInfo())
+    {
+        Point2Raw helpOrigin(SCREENWIDTH/2, (SCREENHEIGHT/2) + ((SCREENHEIGHT/2-5)/cfg.menuScale));
+        Hu_MenuDrawPageHelp(focusObj->helpInfo().toUtf8().constData(), helpOrigin.x, helpOrigin.y);
+    }
 }
 
 Page::Page(Point2Raw const &origin, int flags,
@@ -1176,7 +1185,7 @@ Widget *Page::findObject(int group, int flags)
 {
     foreach(Widget *wi, _widgets)
     {
-        if(wi->isGroupMember(group) && (wi->flags() & flags) == flags)
+        if(wi->group() == group && (wi->flags() & flags) == flags)
             return wi;
     }
     return 0; // Not found.
@@ -1507,9 +1516,16 @@ int Page::timer()
     return _timer;
 }
 
+DENG2_PIMPL_NOREF(Widget)
+{
+    int group;        ///< Object group identifier.
+    String helpInfo;  ///< Additional help information displayed when the widget has focus.
+
+    Instance() : group(0) {}
+};
+
 Widget::Widget()
-    : _group             (0)
-    , _flags             (0)
+    : _flags             (0)
     , _shortcut          (0)
     , _pageFontIdx       (0)
     , _pageColorIdx      (0)
@@ -1520,10 +1536,14 @@ Widget::Widget()
     , _geometry          (0)
     , _page              (0)
     , timer              (0)
+    , d(new Instance)
 {
     de::zap(actions);
 }
 
+Widget::~Widget()
+{}
+
 int Widget::handleEvent(event_t * /*ev*/)
 {
     return 0; // Not handled.
@@ -1592,11 +1612,22 @@ Widget &Widget::setFlags(flagop_t op, int flagsToChange)
     case FO_SET:    _flags |= flagsToChange;   break;
     case FO_TOGGLE: _flags ^= flagsToChange;   break;
 
-    default: DENG2_ASSERT(!"MNObject::SetFlags: Unknown op.");
+    default: DENG2_ASSERT(!"Widget::SetFlags: Unknown op.");
     }
     return *this;
 }
 
+int Widget::group() const
+{
+    return d->group;
+}
+
+Widget &Widget::setGroup(int newGroup)
+{
+    d->group = newGroup;
+    return *this;
+}
+
 int Widget::shortcut()
 {
     return _shortcut;
@@ -1621,11 +1652,6 @@ int Widget::color()
     return _pageColorIdx;
 }
 
-dd_bool Widget::isGroupMember(int group) const
-{
-    return (_group == group);
-}
-
 int Widget_DefaultCommandResponder(Widget *ob, menucommand_e cmd)
 {
     DENG2_ASSERT(ob);
@@ -1674,9 +1700,20 @@ int Widget::execAction(mn_actionid_t id, void *parameters)
     return -1; // NOP
 }
 
+String const &Widget::helpInfo() const
+{
+    return d->helpInfo;
+}
+
+Widget &Widget::setHelpInfo(String newHelpInfo)
+{
+    d->helpInfo = newHelpInfo;
+    return *this;
+}
+
 RectWidget::RectWidget()
     : Widget()
-    , patch      (0)
+    , patch(0)
 {
     Widget::_pageFontIdx  = MENU_FONT1;
     Widget::_pageColorIdx = MENU_COLOR1;