Ticket #3987: firstPlugin.diff

File firstPlugin.diff, 11.4 KB (added by hendrixski@…, 13 years ago)

My first patch, a bunch of doxygen comments to add to MythThemedMenu?

  • mythtv/libs/libmythui/myththemedmenu.h

     
    77class MythThemedMenuPrivate;
    88class MythThemedMenuState;
    99
     10/**
     11 * Finds and parses menu and theme files then applies them to screen then handles actions
     12 * captured by those elements.
     13 */
    1014class MythThemedMenu : public MythScreenType
    1115{
    1216    Q_OBJECT
    1317  public:
     18    /**
     19     * @param cdir directory where theme is stored
     20     * @param menufile name of menu file
     21     * @param parent the screen stack that owns this UI type
     22     * @param name the name of this UI type
     23     * @param allowreorder will buttons be inserted into new rows or pushed back
     24     * @param state theme state associated with this menu
     25     */
    1426    MythThemedMenu(const char *cdir, const char *menufile,
    1527                   MythScreenStack *parent, const char *name,
    1628                   bool allowreorder = true, MythThemedMenuState *state = NULL);
    1729   ~MythThemedMenu();
    1830
     31    /**
     32     * @return true if the theme has been found
     33     */
    1934    bool foundTheme(void);
    2035
     36    /**
     37     * Set the themed menus callback state
     38     *@param lcallback the callback state
     39     *@param data information about the callback state
     40     */
    2141    void setCallback(void (*lcallback)(void *, QString &), void *data);
    2242    void setKillable(void);
    2343
    2444    QString getSelection(void);
    2545
    2646    void ReloadTheme(void);
     47
     48     /**
     49     * @brief Set the exit key to the appropriate button type depending on the database
     50     * context, or set it not to not allow exiting just yet.
     51     */
    2752    void ReloadExitKey(void);
    2853    virtual void aboutToShow(void);
    2954
    3055  protected:
     56     /**
     57     * @return true if handled
     58     */
    3159    virtual bool keyPressEvent(QKeyEvent *e);
     60   
     61    /**
     62     * @brief Interpret mouse gestures on the UI as key events
     63     * @param origtype the orriginating element type from the screen
     64     * @param ge the mouse gesture event
     65     */
    3266    virtual void gestureEvent(MythUIType *origtype, MythGestureEvent *ge);
    3367
    3468  private:
     69    /**
     70     * Initialize creation of a mythThemedMenu
     71     * @param cdir directory where theme is stored
     72     * @param menufile name of menu file
     73     */
    3574    void Init(const char *cdir, const char *menufile);
    3675
    3776    MythThemedMenuPrivate *d;
  • mythtv/libs/libmythui/myththemedmenu.cpp

     
    8888
    8989class MythThemedMenuPrivate;
    9090
     91/**
     92 * @class MyththemedMenuState
     93 * @brief Private class that controls the settings of buttons, logos, backgrounds,
     94 * texts, and more, for the MythThemedMenu class.
     95 */
    9196class MythThemedMenuState: public XMLParseBase
    9297{
    9398  public:
    9499    MythThemedMenuState();
    95100   ~MythThemedMenuState();
    96101
     102    /**
     103     * @brief Parse the menu from the given dir for background, button, logo, arrow,
     104     * and font settings
     105     * @param dir directory where setting may be found
     106     * @param menuname name of menu file from which settings are parsed
     107     * @return true if file exists, opens, and parses correctly
     108     */
    97109    bool parseSettings(const QString &dir, const QString &menuname);
    98110
     111    /**
     112     * @brief Parse through the element's tags and set the button's
     113     * area, spread, center, rows, columns and visible lower limit.
     114     * @param &dir the directory path of background
     115     * @param element QDomElement with information about the background
     116     */
    99117    void parseBackground(const QString &dir, QDomElement &element);
     118
     119    /**
     120     * @brief Parse through the element's tags and set the logo's image and position
     121     * @param dir the directory where logo images may be found
     122     * @param element the DOM element whose nodes describe the logo
     123     */
    100124    void parseLogo(const QString &dir, QDomElement &element);
     125
     126    /**
     127     * @brief Parse through the element's tags to set the arrows image and position
     128     * @param dir directory where arrow images may be found
     129     * @param element DOM element dealing with arrow image and position
     130     */
    101131    void parseArrow(const QString &dir, QDomElement &element, bool up);
     132
     133    /**
     134     * @brief Parse through the element's tags and set the title's image (and
     135     * subsequent mode) and position
     136     * @param dir directory where title images may be found
     137     * @param element DOM element dealing with the title
     138     */
    102139    void parseTitle(const QString &dir, QDomElement &element);
     140
     141    /**
     142     * @brief Parse through the element's tags and set the button's
     143     * definition as normal, active, text, or activetext.
     144     * @param dir the directory where the button images may be found
     145     * @param element the DOM element whose nodes define Buttons
     146     */
    103147    void parseButtonDefinition(const QString &dir, QDomElement &element);
     148
     149    /**
     150     * @brief Parse through the element's tags and set the button's image, activeimage,
     151     * watermarkimage, and offset
     152     * @param dir directory where buttom images may be found
     153     * @param element DOM element dealing with button attributes
     154     */
    104155    void parseButton(const QString &dir, QDomElement &element);
    105156
     157    /**
     158     * @brief Parse through the element's tags and set the text's area,
     159     * fontsize, fontname, positioning, and decorations
     160     * @param attributes text attributes whose font face will be set
     161     * @param element DOM element dealing with text
     162     */
    106163    void parseText(TextAttributes &attributes, QDomElement &element);
     164
     165    /**
     166     * @brief Parse through the element's tags and set the outline's color
     167     * and size
     168     * @param attributes text attributes whose font outline will be set
     169     * @param element DOM element dealing with outline
     170     */
    107171    void parseOutline(TextAttributes &attributes, QDomElement &element);
    108     void parseShadow(TextAttributes &attributes, QDomElement &element);
    109172
     173    /**
     174     * @brief Parse through the element's tags and set the shadow's color,
     175     * offset, and alpha.
     176     * @param attributes text attributes whose font shadow will be set
     177     * @param element DOM dealing with shadow
     178     */
     179   void parseShadow(TextAttributes &attributes, QDomElement &element);
     180
    110181    void Reset(void);
     182
     183    /**
     184     * @brief Set buttons, logo, title icons and text, arrows and watermarks back to
     185     * the defaults
     186     */
    111187    void setDefaults(void);
    112188
    113189    ButtonIcon *getButtonIcon(const QString &type);
     
    167243class MythThemedMenuPrivate: public XMLParseBase
    168244{
    169245  public:
    170     MythThemedMenuPrivate(MythThemedMenu *lparent, const char *cdir,
     246    /**
     247     * @param lparent menu that owns this instance
     248     * @param cdir directory where theme is stored
     249     * @param lstate corresponding settings of the theme
     250     */
     251   MythThemedMenuPrivate(MythThemedMenu *lparent, const char *cdir,
    171252                      MythThemedMenuState *lstate);
    172253   ~MythThemedMenuPrivate();
    173254
     255    /**
     256     * @brief Delegate key event to appropriate action for keyHandler()
     257     * @param e key pressed
     258     * @return true if key event was properly handled
     259     */
    174260    bool keyPressHandler(QKeyEvent *e);
     261
     262    /**
     263     * @brief Interpret key presses on the menu into the appropriate actions
     264     * @param actions list of key presses to be interpreted
     265     * @param fullexit should this be allowed to exit the program if other conditions
     266     * are right
     267     */
    175268    bool keyHandler(QStringList &actions, bool fullexit);
    176269
     270    /**
     271     * @brief Reset and reparse everything
     272     * @return true if theme was reloaded correctly
     273     */
    177274    bool ReloadTheme(void);
    178275
     276    /**
     277     * @brief Parse the themebuttons to be added based on the name of the menu file
     278     * provided in the parameters
     279     * @param menuname name of menu file
     280     * @return true if passed mainmenu.xml
     281     */
    179282    bool parseMenu(const QString &menuname);
    180 
     283   
     284    /**
     285     * @brief Parse the element's tags and set the ThemeButton's type, text, depends,
     286     * and action.  Then add the button.
     287     * @param element DOM element describing features of the themeButton
     288     */
    181289    void parseThemeButton(QDomElement &element);
    182290
     291    /**
     292     * @brief Create a new MythThemedButton based on the MythThemedMenuState m_state
     293     * and the type, text, alt-text and action provided in the parameters.
     294     * @param type type of button to be created
     295     * @param text text to appear on the button
     296     * @param alttext alttext to appear when required
     297     * @param action actions to be associated with button
     298     */
    183299    void addButton(const QString &type, const QString &text,
    184300                   const QString &alttext, const QStringList &action);
     301 
     302    /**
     303     * @brief Properly lay out all of the buttons that were added with addButton
     304     * @return true if there are more than 0 rows or columns
     305     */
    185306    bool layoutButtons(void);
     307   
     308    /**
     309     * @brief Place buttons in position and set them visible and active
     310     * @param resetpos whether or not to reset the active button to the first one on the
     311     * buttonlist
     312     */
    186313    void positionButtons(bool resetpos);
    187314    bool makeRowVisible(int newrow, int oldrow);
    188315
     316    /**
     317     * @brief Handle actions from the menu requested by the user such as "exectv, jump,
     318     * or menu
     319     * @param action the action to be handled
     320     * @return true if the action is not to EXEC another program
     321     */
    189322    bool handleAction(const QString &action);
    190323    bool findDepends(const QString &fileList);
     324
     325    /**
     326     * @brief Locate the appropriate menu file from which to parse the menu
     327     * @param menuname the name of the menu file you want to find
     328     * @return the directory in which the menu file is found
     329     */
    191330    QString findMenuFile(const QString &menuname);
    192331
     332    /**
     333     * @brief Show scroll arrows if needed
     334     */
    193335    void checkScrollArrows(void);
    194336
     337     /**
     338     * Check timestamp and password settings against database and
     339     * @param timestamp_setting time settings to be checked
     340     * @param password_setting password to be checked
     341     * @param text the message text to be displayed
     342     * @return true if pin code checks out
     343     */
    195344    bool checkPinCode(const QString &timestamp_setting,
    196345                      const QString &password_setting,
    197346                      const QString &text);
    198347 
     348    /**
     349     * Set up UI according to the corresponding mythThemedMenuState
     350     */
    199351    void SetupUITypes();
    200352
     353    /**
     354     * @brief Interpret mouse gestures on the UI as key events
     355     * @param origtype the orriginating element type from the screen
     356     * @param ge the mouse gesture event
     357     * @return true if the gesture event was click or left
     358     */
    201359    bool gestureEvent(MythUIType *origtype, MythGestureEvent *ge);
    202360
    203361    void updateLCD(void);
     
    261419    Reset();
    262420}
    263421
     422
    264423void MythThemedMenuState::Reset(void)
    265424{
    266425    if (logo)
     
    21052264       
    21062265    return "";
    21072266}
    2108 
    21092267bool MythThemedMenuPrivate::handleAction(const QString &action)
    21102268{
    21112269    if (action.left(5) == "EXEC ")
     
    22152373    return true;   
    22162374}
    22172375
     2376
    22182377bool MythThemedMenuPrivate::findDepends(const QString &fileList)
    22192378{
    22202379    QStringList files = QStringList::split(" ", fileList);
     
    23742533        d->foundtheme = false;
    23752534}
    23762535
     2536
    23772537bool MythThemedMenu::keyPressEvent(QKeyEvent *e)
    23782538{
    23792539    if (d->ignorekeys)