From 2b9977a334e933a92f81efe7d458ebd9a8bb8d79 Mon Sep 17 00:00:00 2001 From: Tobias Loose Date: Sun, 8 Dec 2013 10:48:15 +0100 Subject: [PATCH] Rename methods for consistency and add source code doc to DeckView.h --- projects/mtg/include/CarouselDeckView.h | 8 +- projects/mtg/include/DeckView.h | 199 +++++++++++++++++++++-- projects/mtg/include/GridDeckView.h | 6 +- projects/mtg/src/CarouselDeckView.cpp | 42 ++--- projects/mtg/src/DeckView.cpp | 15 +- projects/mtg/src/GameStateDeckViewer.cpp | 4 +- projects/mtg/src/GridDeckView.cpp | 36 ++-- 7 files changed, 243 insertions(+), 67 deletions(-) diff --git a/projects/mtg/include/CarouselDeckView.h b/projects/mtg/include/CarouselDeckView.h index 1c22262b4..7a9b67ee3 100644 --- a/projects/mtg/include/CarouselDeckView.h +++ b/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 changeFilter(int offset); + void changePositionAnimated(int offset); + void changeFilterAnimated(int offset); MTGCard *getActiveCard(); private: diff --git a/projects/mtg/include/DeckView.h b/projects/mtg/include/DeckView.h index 0534bfaf2..7feec1226 100644 --- a/projects/mtg/include/DeckView.h +++ b/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 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_ diff --git a/projects/mtg/include/GridDeckView.h b/projects/mtg/include/GridDeckView.h index 981665ac1..3e85e6288 100644 --- a/projects/mtg/include/GridDeckView.h +++ b/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 changeFilter(int offset); + void changePositionAnimated(int offset); + void changeFilterAnimated(int offset); MTGCard *getActiveCard(); private: diff --git a/projects/mtg/src/CarouselDeckView.cpp b/projects/mtg/src/CarouselDeckView.cpp index 7b03e59b7..32b5e43cc 100644 --- a/projects/mtg/src/CarouselDeckView.cpp +++ b/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(getCardRep(3).card); - WResourceManager::Instance()->RetrieveCard(getCardRep(4).card); - WResourceManager::Instance()->RetrieveCard(getCardRep(2).card); - WResourceManager::Instance()->RetrieveCard(getCardRep(5).card); - WResourceManager::Instance()->RetrieveCard(getCardRep(1).card); - WResourceManager::Instance()->RetrieveCard(getCardRep(6).card); + WResourceManager::Instance()->RetrieveCard(mCards[0].card); + WResourceManager::Instance()->RetrieveCard(mCards[3].card); + WResourceManager::Instance()->RetrieveCard(mCards[4].card); + WResourceManager::Instance()->RetrieveCard(mCards[2].card); + WResourceManager::Instance()->RetrieveCard(mCards[5].card); + WResourceManager::Instance()->RetrieveCard(mCards[1].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; } diff --git a/projects/mtg/src/DeckView.cpp b/projects/mtg/src/DeckView.cpp index 8715bfef2..682b75957 100644 --- a/projects/mtg/src/DeckView.cpp +++ b/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); diff --git a/projects/mtg/src/GameStateDeckViewer.cpp b/projects/mtg/src/GameStateDeckViewer.cpp index b660e50a1..20713d675 100644 --- a/projects/mtg/src/GameStateDeckViewer.cpp +++ b/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; } diff --git a/projects/mtg/src/GridDeckView.cpp b/projects/mtg/src/GridDeckView.cpp index a7a8e32ac..59c1fbdd8 100644 --- a/projects/mtg/src/GridDeckView.cpp +++ b/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