Rename methods for consistency and add source code doc

to DeckView.h

projects/mtg/include/CarouselDeckView.h

@@ -18,10 +18,10 @@ public:
     void Reset();
 
     void UpdateViewState(float dt);
-    void UpdateCardPosition(CardRep &rep, int index);
+    void UpdateCardPosition(int index);
     void renderCard(int index)
     {
-        int alpha = (int) (255 * (getCardRep(index).scale + 1.0 - max_scale));
+        int alpha = (int) (255 * (mCards[index].scale + 1.0 - max_scale));
         DeckView::renderCard(index, alpha);
     }
 
@@ -31,8 +31,8 @@ public:
     MTGCard * Click(int x, int y);
     MTGCard * Click();
 
-    void changePosition(int offset);
+    void changePositionAnimated(int offset);
-    void changeFilter(int offset);
+    void changeFilterAnimated(int offset);
 
     MTGCard *getActiveCard();
 private:

projects/mtg/include/DeckView.h

@@ -9,56 +9,233 @@
 #include "WResourceManager.h"
 #include "Pos.h"
 
-
+/*! \brief A abstract base class for deck views
+ *
+ * The deck editor uses a deck view to present the cards
+ * e.g. in a circular "Carousel" layout or in a flat grid
+ * layout. Both layouts inherit this base class to ensure
+ * a common interface which the deck editor can rely on.
+ */
 class DeckView
 {
 protected:
+    /*! \brief defines the delay until additional card informations get shown
+     *
+     * \note I am not entirely sure about that
+     */
     static const float no_user_activity_show_card_delay;
 
-public:
+    /*! \brief Represents a card for internal use in the deck view
+     *
+     * It stores positional information and a pointer to the actual card structure.
+     */
     struct CardRep{
         float x;
         float y;
         float scale;
         MTGCard * card;
     };
-
+public:
+    /*! \brief Defines if the filter needs an update
+     *
+     * The owner of the deck that is shown is responsible for updating the filters.
+     */
     bool dirtyFilters;
+
+    /*! \brief Defines if the card positions need an update
+     *
+     * If the card positions are dirty, UpdateCardPosition will get called on
+     * all cards during Update(float dt);
+     *
+     * \see Update
+     * \see UpdateCardPosition
+     */
     bool dirtyCardPos;
 
+    /*! \brief Constructs the view and initializes datamembers
+     *
+     * It sets the dirty states to true, the currently shown deck to NULL and selects filter 0.
+     *
+     * \param numberOfCards the number of cards the view handles (this includes hidden cards for caching)
+     */
     DeckView(int numberOfCards);
+
+    /*! \brief Does nothing but is needed to ensure proper deletion of derived classes.
+     */
     virtual ~DeckView();
+
+    /*! \brief Resets nearly all datamembers to their initial values
+     *
+     * Does not reset mCards.
+     */
     virtual void Reset();
 
-    //advances the view and card representations
+    /*! \brief Advances the view by dt time units
+     *
+     * This method calls UpdateViewState unconditionally and UpdateCardPosition on every card
+     * if dirtyCardPos is set. It then resets dirtyCardPos.
+     *
+     * \param dt the number of time units to advance
+     * \see UpdateViewState
+     * \see UpdateCardPosition
+     */
     void Update(float dt);
-    virtual void SetDeck(DeckDataWrapper *toShow);
+
+    /*! \brief Sets the deck that this view shows
+     *
+     * This method replaces the currently shown deck with toShow, sets all dirty states and
+     * reloads the mtg cards. No ownership changes.
+     *
+     * \param toShow the deck to show
+     * \see reloadIndexes
+     */
+    void SetDeck(DeckDataWrapper *toShow);
+
+    /*! \brief Returns a pointer to the current deck.
+     */
     DeckDataWrapper *deck();
-    void SwitchFilter(int delta);
+
-    void SwitchPosition(int delta);
+    /*! \brief Performs an immediate switch of the filter without animations
+     *
+     * This method rotates the currently selected filter by delta and sets dirtyFilters.
+     *
+     * \param delta the filter to select relatively to the currently selected filter
+     * \see dirtyFilters
+     */
+    void changeFilter(int delta);
+
+    /*! \brief Performs an immediate switch of the position without animations
+     *
+     * If the i-th card stored in mCards points to the j-th card in the deck, it will point
+     * to the (j+delta)-th card after this method is called. No dirty states are set.
+     *
+     * \param delta the number of cards to advances
+     * \see mCards
+     */
+    void changePosition(int delta);
+
+    /*! \brief Returns the number of the currently selected filter
+     *
+     * \return the currently selected filter
+     */
     int filter();
+
+    /*! \brief Reloads the mtg card pointers of mCards from the deck
+     *
+     * This is called when: We change the position in the deck or the deck structure changes
+     * (due to filtering or addition or removal of cards).
+     */
     void reloadIndexes();
+
+    /*! \brief Returns the current position in the deck
+     */
     int getPosition();
 
+    /*! \brief Renders the view
+     */
     virtual void Render() = 0;
+
+    /*! \brief Reacts to selections by a pointer device (e. g. mouse, touch)
+     *
+     * If the selection in view internal i. e. a card got selected, there is
+     * no outside action performed and this method will return NULL. If a action got
+     * triggered i. e. a selected card was activated, it returns that card
+     * for further handling by the caller.
+     *
+     * \param x the x coordinate of the pointer during the action
+     * \param y the y coordinate of the pointer during the action
+     * \returns the card the action corresponds to
+     */
     virtual MTGCard * Click(int x, int y) = 0;
+
+    /*! \brief Reacts to selections by pointerless devices (e. g. buttons)
+     *
+     * \see Click(int x, int y)
+     * \returns the card the actions corresponds to
+     */
     virtual MTGCard * Click() = 0;
+
+    /*! \brief Handles ordinary button presses
+     *
+     * \param the pressed JButton
+     * \returns true if the view reacted to the button and false otherwise
+     */
     virtual bool ButtonPressed(Buttons button) = 0;
+
+    /*! \brief Returns the currently active card
+     */
     virtual MTGCard *getActiveCard() = 0;
-    virtual void changePosition(int offset) = 0;
+
-    virtual void changeFilter(int offset) = 0;
+    /*! \brief Changes the position by a given offset
+     *
+     * Advances the view by offset cards and animates the change.
+     *
+     * \param offset the number of positions to advance
+     */
+    virtual void changePositionAnimated(int offset) = 0;
+
+    /*! \brief Changes the filter by a given offset
+     *
+     * Rotates the selected filter by the given offset and animates the change.
+     */
+    virtual void changeFilterAnimated(int offset) = 0;
 protected:
+
+    /*! \brief The number of time units since an user activity occurred
+     */
     float last_user_activity;
+
+    /*! \brief The currently selected filter
+     */
     int mFilter;
+
+    /*! \brief The currently selected deck
+     *
+     * This class does not take ownership of the deck
+     */
     DeckDataWrapper *mCurrentDeck;
+
+    /*! \brief The card positions and pointers
+     */
     vector<CardRep> mCards;
 
-    CardRep& getCardRep(unsigned int index);
+    /*! \brief Renders a card with given alpha value
+     *
+     * \param index of the card in mCards to render
+     * \param alpha the alpha value of the card
+     * \param asThumbnail renders the thumbnail image of the card if set to true
+     *
+     * \see mCards
+     */
     void renderCard(int index, int alpha, bool asThumbnail = false);
+
+    /*! \brief Returns the index in mCards of the card that is nearest to the given point
+     *
+     * \note This method uses the euclidian distance to the center of the card
+     *
+     * \param x the reference points x coordinate
+     * \param y the reference points y coordinate
+     * \returns the index of the nearest card to the reference point and -1 of mCards is empty
+     */
     int getCardIndexNextTo(int x, int y);
 private:
+
+    /*! \brief Updates the state of the view e. g. view transitions
+     *
+     * \param dt the passes time since the last update
+     */
     virtual void UpdateViewState(float dt) = 0;
-    virtual void UpdateCardPosition(CardRep& rep, int index) = 0;
+
+    /*! \brief Updates the given card reps positional members
+     *
+     * This method is called from Update when dirtyCardPos is set
+     *
+     * \param index the index in mCards of the card to update
+     *
+     * \see Update
+     * \see mCards
+     */
+    virtual void UpdateCardPosition(int index) = 0;
 };
 
 #endif // _DECK_VIEW_H_

projects/mtg/include/GridDeckView.h

@@ -17,15 +17,15 @@ public:
     void Reset();
 
     void UpdateViewState(float dt);
-    void UpdateCardPosition(CardRep &rep, int index);
+    void UpdateCardPosition(int index);
 
     void Render();
     bool ButtonPressed(Buttons button);
     MTGCard * Click(int x, int y);
     MTGCard * Click();
 
-    void changePosition(int offset);
+    void changePositionAnimated(int offset);
-    void changeFilter(int offset);
+    void changeFilterAnimated(int offset);
 
     MTGCard *getActiveCard();
 private:

projects/mtg/src/CarouselDeckView.cpp

@@ -21,12 +21,12 @@ void CarouselDeckView::UpdateViewState(float dt)
 
         if(mScrollOffset <= -1.0f)
         {
-            SwitchPosition(-1);
+            changePosition(-1);
             mScrollEasing.translate(1.0f);
         }
         else if(mScrollOffset >= 1.0f)
         {
-            SwitchPosition(1);
+            changePosition(1);
             mScrollEasing.translate(-1.0f);
         }
 
@@ -43,7 +43,7 @@ void CarouselDeckView::UpdateViewState(float dt)
             if(mSlideOffset < -1.0f)
             {
                 mSlideEasing.translate(2.0f);
-                SwitchFilter(1);
+                changeFilter(1);
             }
         }
         else if(mSlideOffset > mSlideEasing.start_value)
@@ -52,7 +52,7 @@ void CarouselDeckView::UpdateViewState(float dt)
             if(mSlideOffset > 1.0f)
             {
                 mSlideEasing.translate(-2.0f);
-                SwitchFilter(-1);
+                changeFilter(-1);
             }
         }
 
@@ -60,8 +60,10 @@ void CarouselDeckView::UpdateViewState(float dt)
     }
 }
 
-void CarouselDeckView::UpdateCardPosition(CardRep &rep, int index)
+void CarouselDeckView::UpdateCardPosition(int index)
 {
+    CardRep &rep = mCards[index];
+
     float rotation = mScrollOffset + 8 - index;
 
     rep.x = x_center + cos((rotation) * M_PI / 12) * (right_border - x_center);
@@ -84,13 +86,13 @@ void CarouselDeckView::Render()
     // in a different order, ie the center card should appear first, then the adjacent ones
     if (WResourceManager::Instance()->IsThreaded())
     {
-        WResourceManager::Instance()->RetrieveCard(getCardRep(0).card);
+        WResourceManager::Instance()->RetrieveCard(mCards[0].card);
-        WResourceManager::Instance()->RetrieveCard(getCardRep(3).card);
+        WResourceManager::Instance()->RetrieveCard(mCards[3].card);
-        WResourceManager::Instance()->RetrieveCard(getCardRep(4).card);
+        WResourceManager::Instance()->RetrieveCard(mCards[4].card);
-        WResourceManager::Instance()->RetrieveCard(getCardRep(2).card);
+        WResourceManager::Instance()->RetrieveCard(mCards[2].card);
-        WResourceManager::Instance()->RetrieveCard(getCardRep(5).card);
+        WResourceManager::Instance()->RetrieveCard(mCards[5].card);
-        WResourceManager::Instance()->RetrieveCard(getCardRep(1).card);
+        WResourceManager::Instance()->RetrieveCard(mCards[1].card);
-        WResourceManager::Instance()->RetrieveCard(getCardRep(6).card);
+        WResourceManager::Instance()->RetrieveCard(mCards[6].card);
     }
 
     renderCard(6);
@@ -123,19 +125,19 @@ bool CarouselDeckView::ButtonPressed(Buttons button)
     switch(button)
     {
     case JGE_BTN_LEFT:
-        changePosition(-1);
+        changePositionAnimated(-1);
         last_user_activity = 0;
         break;
     case JGE_BTN_RIGHT:
-        changePosition(1);
+        changePositionAnimated(1);
         last_user_activity = 0;
         break;
     case JGE_BTN_UP:
-        changeFilter(1);
+        changeFilterAnimated(1);
         last_user_activity = 0;
         break;
     case JGE_BTN_DOWN:
-        changeFilter(-1);
+        changeFilterAnimated(-1);
         last_user_activity = 0;
         break;
     default:
@@ -157,7 +159,7 @@ MTGCard * CarouselDeckView::Click(int x, int y)
         }
         else
         {
-            changePosition(n - 2);
+            changePositionAnimated(n - 2);
         }
     }
 
@@ -176,14 +178,14 @@ MTGCard *CarouselDeckView::Click()
     }
 }
 
-void CarouselDeckView::changePosition(int offset)
+void CarouselDeckView::changePositionAnimated(int offset)
 {
     mScrollEasing.start((float)offset, (float)(0.3f*abs(offset)));
 
     last_user_activity = 0;
 }
 
-void CarouselDeckView::changeFilter(int offset)
+void CarouselDeckView::changeFilterAnimated(int offset)
 {
     if(offset < 0)
     {
@@ -198,6 +200,6 @@ void CarouselDeckView::changeFilter(int offset)
 
 MTGCard *CarouselDeckView::getActiveCard()
 {
-    return getCardRep(2).card;
+    return mCards[2].card;
 }
 

projects/mtg/src/DeckView.cpp

@@ -35,7 +35,7 @@ void DeckView::Update(float dt)
     {
         for(unsigned int i = 0; i < mCards.size(); ++i)
         {
-            UpdateCardPosition(mCards[i], i);
+            UpdateCardPosition(i);
         }
         dirtyCardPos = false;
     }
@@ -54,14 +54,14 @@ DeckDataWrapper* DeckView::deck()
     return mCurrentDeck;
 }
 
-void DeckView::SwitchFilter(int delta)
+void DeckView::changeFilter(int delta)
 {
     unsigned int FilterCount = Constants::NB_Colors + 1;
     mFilter = (FilterCount + mFilter + delta) % FilterCount;
     dirtyFilters = true;
 }
 
-void DeckView::SwitchPosition(int delta)
+void DeckView::changePosition(int delta)
 {
     for(int i = 0; i < delta; ++i)
     {
@@ -92,16 +92,11 @@ void DeckView::reloadIndexes()
     }
 }
 
-DeckView::CardRep& DeckView::getCardRep(unsigned int index)
-{
-    return mCards[index];
-}
-
 void DeckView::renderCard(int index, int alpha, bool asThumbnail)
 {
     WFont * mFont = WResourceManager::Instance()->GetWFont(Fonts::MAIN_FONT);
 
-    const CardRep& cardPosition = getCardRep(index);
+    const CardRep& cardPosition = mCards[index];
 
     if (!cardPosition.card) return;
 
@@ -187,7 +182,7 @@ int DeckView::getCardIndexNextTo(int x, int y)
 
     for(unsigned int i = 0; i < mCards.size(); i++)
     {
-        const CardRep& cardPosition = getCardRep(i);
+        const CardRep& cardPosition = mCards[i];
 
         float dx = (x - cardPosition.x);
         float dy = (y - cardPosition.y);

projects/mtg/src/GameStateDeckViewer.cpp

@@ -1532,11 +1532,11 @@ void GameStateDeckViewer::OnScroll(int inXVelocity, int inYVelocity)
         {
             //FIXME: this 500 is a bit arbitrary
             int numCards = (magnitude / 500) % 8;
-            mView->changePosition(flickRight ? numCards : - numCards);
+            mView->changePositionAnimated(flickRight ? numCards : - numCards);
         }
     }
     else
-        mView->changeFilter(flickUp ? 1 : -1);
+        mView->changeFilterAnimated(flickUp ? 1 : -1);
 
     last_user_activity = 0;
 }

projects/mtg/src/GridDeckView.cpp

@@ -37,13 +37,13 @@ void GridDeckView::UpdateViewState(float dt)
 
         if(mScrollOffset <= -1.0f)
         {
-            SwitchPosition(2);
+            changePosition(2);
             moveSelection(-2, false);
             mScrollEasing.translate(1.0f);
         }
         else if(mScrollOffset >= 1.0f)
         {
-            SwitchPosition(-2);
+            changePosition(-2);
             moveSelection(2, false);
             mScrollEasing.translate(-1.0f);
         }
@@ -58,20 +58,22 @@ void GridDeckView::UpdateViewState(float dt)
         if(mSlideOffset < -1.0f)
         {
             mSlideEasing.translate(2.0f);
-            SwitchFilter(1);
+            changeFilter(1);
         }
         else if(mSlideOffset > 1.0f)
         {
             mSlideEasing.translate(-2.0f);
-            SwitchFilter(-1);
+            changeFilter(-1);
         }
 
         dirtyCardPos = true;
     }
 }
 
-void GridDeckView::UpdateCardPosition(CardRep &rep, int index)
+void GridDeckView::UpdateCardPosition(int index)
 {
+    CardRep &rep = mCards[index];
+
     int col = index / mRows;
     int row = index % mRows;
     float colWidth = SCREEN_WIDTH_F / (mCols - 3);
@@ -121,7 +123,7 @@ void GridDeckView::Render()
         {
             if (WResourceManager::Instance()->IsThreaded())
             {
-                WResourceManager::Instance()->RetrieveCard(getCardRep(i).card, RETRIEVE_THUMB);
+                WResourceManager::Instance()->RetrieveCard(mCards[i].card, RETRIEVE_THUMB);
             }
             renderCard(i, 255, true);
         }
@@ -129,7 +131,7 @@ void GridDeckView::Render()
         {
             if (WResourceManager::Instance()->IsThreaded())
             {
-                WResourceManager::Instance()->RetrieveCard(getCardRep(i).card);
+                WResourceManager::Instance()->RetrieveCard(mCards[i].card);
             }
         }
     }
@@ -146,22 +148,22 @@ bool GridDeckView::ButtonPressed(Buttons button)
     {
     case JGE_BTN_LEFT:
         if(mButtonMode) moveSelection(-2, true);
-        else changePosition(-1);
+        else changePositionAnimated(-1);
         last_user_activity = 0;
         break;
     case JGE_BTN_RIGHT:
         if(mButtonMode) moveSelection(2, true);
-        else changePosition(1);
+        else changePositionAnimated(1);
         last_user_activity = 0;
         break;
     case JGE_BTN_UP:
         if(mButtonMode) moveSelection(-1, true);
-        else changeFilter(1);
+        else changeFilterAnimated(1);
         last_user_activity = 0;
         break;
     case JGE_BTN_DOWN:
         if(mButtonMode) moveSelection(1, true);
-        else changeFilter(-1);
+        else changeFilterAnimated(-1);
         last_user_activity = 0;
         break;
     case JGE_BTN_CTRL:
@@ -193,11 +195,11 @@ MTGCard * GridDeckView::Click(int x, int y)
         }
         else if(n < 4)
         {
-            changePosition(-1);
+            changePositionAnimated(-1);
         }
         else if(n >= 12)
         {
-            changePosition(1);
+            changePositionAnimated(1);
         }
         else
         {
@@ -229,13 +231,13 @@ MTGCard * GridDeckView::Click()
     return NULL;
 }
 
-void GridDeckView::changePosition(int offset)
+void GridDeckView::changePositionAnimated(int offset)
 {
     mScrollEasing.start(-1.0f * offset, scroll_animation_duration * abs(offset));
     last_user_activity = 0;
 }
 
-void GridDeckView::changeFilter(int offset)
+void GridDeckView::changeFilterAnimated(int offset)
 {
     if(offset < 0)
     {
@@ -268,11 +270,11 @@ void GridDeckView::moveSelection(int offset, bool alignIfOutOfBounds)
     {
         if(mCurrentSelection < 4)
         {
-            changePosition(-1);
+            changePositionAnimated(-1);
         }
         else if(mCurrentSelection >= 12)
         {
-            changePosition(1);
+            changePositionAnimated(1);
         }
     }
     else