Index: mythtv/libs/libmythui/myththemedmenu.h =================================================================== --- mythtv/libs/libmythui/myththemedmenu.h (revision 14509) +++ mythtv/libs/libmythui/myththemedmenu.h (working copy) @@ -7,31 +7,70 @@ class MythThemedMenuPrivate; class MythThemedMenuState; +/** + * Finds and parses menu and theme files then applies them to screen then handles actions + * captured by those elements. + */ class MythThemedMenu : public MythScreenType { Q_OBJECT public: + /** + * @param cdir directory where theme is stored + * @param menufile name of menu file + * @param parent the screen stack that owns this UI type + * @param name the name of this UI type + * @param allowreorder will buttons be inserted into new rows or pushed back + * @param state theme state associated with this menu + */ MythThemedMenu(const char *cdir, const char *menufile, MythScreenStack *parent, const char *name, bool allowreorder = true, MythThemedMenuState *state = NULL); ~MythThemedMenu(); + /** + * @return true if the theme has been found + */ bool foundTheme(void); + /** + * Set the themed menus callback state + *@param lcallback the callback state + *@param data information about the callback state + */ void setCallback(void (*lcallback)(void *, QString &), void *data); void setKillable(void); QString getSelection(void); void ReloadTheme(void); + + /** + * @brief Set the exit key to the appropriate button type depending on the database + * context, or set it not to not allow exiting just yet. + */ void ReloadExitKey(void); virtual void aboutToShow(void); protected: + /** + * @return true if handled + */ virtual bool keyPressEvent(QKeyEvent *e); + + /** + * @brief Interpret mouse gestures on the UI as key events + * @param origtype the orriginating element type from the screen + * @param ge the mouse gesture event + */ virtual void gestureEvent(MythUIType *origtype, MythGestureEvent *ge); private: + /** + * Initialize creation of a mythThemedMenu + * @param cdir directory where theme is stored + * @param menufile name of menu file + */ void Init(const char *cdir, const char *menufile); MythThemedMenuPrivate *d; Index: mythtv/libs/libmythui/myththemedmenu.cpp =================================================================== --- mythtv/libs/libmythui/myththemedmenu.cpp (revision 14509) +++ mythtv/libs/libmythui/myththemedmenu.cpp (working copy) @@ -88,26 +88,102 @@ class MythThemedMenuPrivate; +/** + * @class MyththemedMenuState + * @brief Private class that controls the settings of buttons, logos, backgrounds, + * texts, and more, for the MythThemedMenu class. + */ class MythThemedMenuState: public XMLParseBase { public: MythThemedMenuState(); ~MythThemedMenuState(); + /** + * @brief Parse the menu from the given dir for background, button, logo, arrow, + * and font settings + * @param dir directory where setting may be found + * @param menuname name of menu file from which settings are parsed + * @return true if file exists, opens, and parses correctly + */ bool parseSettings(const QString &dir, const QString &menuname); + /** + * @brief Parse through the element's tags and set the button's + * area, spread, center, rows, columns and visible lower limit. + * @param &dir the directory path of background + * @param element QDomElement with information about the background + */ void parseBackground(const QString &dir, QDomElement &element); + + /** + * @brief Parse through the element's tags and set the logo's image and position + * @param dir the directory where logo images may be found + * @param element the DOM element whose nodes describe the logo + */ void parseLogo(const QString &dir, QDomElement &element); + + /** + * @brief Parse through the element's tags to set the arrows image and position + * @param dir directory where arrow images may be found + * @param element DOM element dealing with arrow image and position + */ void parseArrow(const QString &dir, QDomElement &element, bool up); + + /** + * @brief Parse through the element's tags and set the title's image (and + * subsequent mode) and position + * @param dir directory where title images may be found + * @param element DOM element dealing with the title + */ void parseTitle(const QString &dir, QDomElement &element); + + /** + * @brief Parse through the element's tags and set the button's + * definition as normal, active, text, or activetext. + * @param dir the directory where the button images may be found + * @param element the DOM element whose nodes define Buttons + */ void parseButtonDefinition(const QString &dir, QDomElement &element); + + /** + * @brief Parse through the element's tags and set the button's image, activeimage, + * watermarkimage, and offset + * @param dir directory where buttom images may be found + * @param element DOM element dealing with button attributes + */ void parseButton(const QString &dir, QDomElement &element); + /** + * @brief Parse through the element's tags and set the text's area, + * fontsize, fontname, positioning, and decorations + * @param attributes text attributes whose font face will be set + * @param element DOM element dealing with text + */ void parseText(TextAttributes &attributes, QDomElement &element); + + /** + * @brief Parse through the element's tags and set the outline's color + * and size + * @param attributes text attributes whose font outline will be set + * @param element DOM element dealing with outline + */ void parseOutline(TextAttributes &attributes, QDomElement &element); - void parseShadow(TextAttributes &attributes, QDomElement &element); + /** + * @brief Parse through the element's tags and set the shadow's color, + * offset, and alpha. + * @param attributes text attributes whose font shadow will be set + * @param element DOM dealing with shadow + */ + void parseShadow(TextAttributes &attributes, QDomElement &element); + void Reset(void); + + /** + * @brief Set buttons, logo, title icons and text, arrows and watermarks back to + * the defaults + */ void setDefaults(void); ButtonIcon *getButtonIcon(const QString &type); @@ -167,37 +243,119 @@ class MythThemedMenuPrivate: public XMLParseBase { public: - MythThemedMenuPrivate(MythThemedMenu *lparent, const char *cdir, + /** + * @param lparent menu that owns this instance + * @param cdir directory where theme is stored + * @param lstate corresponding settings of the theme + */ + MythThemedMenuPrivate(MythThemedMenu *lparent, const char *cdir, MythThemedMenuState *lstate); ~MythThemedMenuPrivate(); + /** + * @brief Delegate key event to appropriate action for keyHandler() + * @param e key pressed + * @return true if key event was properly handled + */ bool keyPressHandler(QKeyEvent *e); + + /** + * @brief Interpret key presses on the menu into the appropriate actions + * @param actions list of key presses to be interpreted + * @param fullexit should this be allowed to exit the program if other conditions + * are right + */ bool keyHandler(QStringList &actions, bool fullexit); + /** + * @brief Reset and reparse everything + * @return true if theme was reloaded correctly + */ bool ReloadTheme(void); + /** + * @brief Parse the themebuttons to be added based on the name of the menu file + * provided in the parameters + * @param menuname name of menu file + * @return true if passed mainmenu.xml + */ bool parseMenu(const QString &menuname); - + + /** + * @brief Parse the element's tags and set the ThemeButton's type, text, depends, + * and action. Then add the button. + * @param element DOM element describing features of the themeButton + */ void parseThemeButton(QDomElement &element); + /** + * @brief Create a new MythThemedButton based on the MythThemedMenuState m_state + * and the type, text, alt-text and action provided in the parameters. + * @param type type of button to be created + * @param text text to appear on the button + * @param alttext alttext to appear when required + * @param action actions to be associated with button + */ void addButton(const QString &type, const QString &text, const QString &alttext, const QStringList &action); + + /** + * @brief Properly lay out all of the buttons that were added with addButton + * @return true if there are more than 0 rows or columns + */ bool layoutButtons(void); + + /** + * @brief Place buttons in position and set them visible and active + * @param resetpos whether or not to reset the active button to the first one on the + * buttonlist + */ void positionButtons(bool resetpos); bool makeRowVisible(int newrow, int oldrow); + /** + * @brief Handle actions from the menu requested by the user such as "exectv, jump, + * or menu + * @param action the action to be handled + * @return true if the action is not to EXEC another program + */ bool handleAction(const QString &action); bool findDepends(const QString &fileList); + + /** + * @brief Locate the appropriate menu file from which to parse the menu + * @param menuname the name of the menu file you want to find + * @return the directory in which the menu file is found + */ QString findMenuFile(const QString &menuname); + /** + * @brief Show scroll arrows if needed + */ void checkScrollArrows(void); + /** + * Check timestamp and password settings against database and + * @param timestamp_setting time settings to be checked + * @param password_setting password to be checked + * @param text the message text to be displayed + * @return true if pin code checks out + */ bool checkPinCode(const QString ×tamp_setting, const QString &password_setting, const QString &text); + /** + * Set up UI according to the corresponding mythThemedMenuState + */ void SetupUITypes(); + /** + * @brief Interpret mouse gestures on the UI as key events + * @param origtype the orriginating element type from the screen + * @param ge the mouse gesture event + * @return true if the gesture event was click or left + */ bool gestureEvent(MythUIType *origtype, MythGestureEvent *ge); void updateLCD(void); @@ -261,6 +419,7 @@ Reset(); } + void MythThemedMenuState::Reset(void) { if (logo) @@ -2105,7 +2264,6 @@ return ""; } - bool MythThemedMenuPrivate::handleAction(const QString &action) { if (action.left(5) == "EXEC ") @@ -2215,6 +2373,7 @@ return true; } + bool MythThemedMenuPrivate::findDepends(const QString &fileList) { QStringList files = QStringList::split(" ", fileList); @@ -2374,6 +2533,7 @@ d->foundtheme = false; } + bool MythThemedMenu::keyPressEvent(QKeyEvent *e) { if (d->ignorekeys)