/indra/newview/llteleporthistory.h

  1/** 
  2 * @file llteleporthistory.h
  3 * @brief Teleport history
  4 *
  5 * $LicenseInfo:firstyear=2009&license=viewerlgpl$
  6 * Second Life Viewer Source Code
  7 * Copyright (C) 2010, Linden Research, Inc.
  8 * 
  9 * This library is free software; you can redistribute it and/or
 10 * modify it under the terms of the GNU Lesser General Public
 11 * License as published by the Free Software Foundation;
 12 * version 2.1 of the License only.
 13 * 
 14 * This library is distributed in the hope that it will be useful,
 15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 17 * Lesser General Public License for more details.
 18 * 
 19 * You should have received a copy of the GNU Lesser General Public
 20 * License along with this library; if not, write to the Free Software
 21 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 22 * 
 23 * Linden Research, Inc., 945 Battery Street, San Francisco, CA  94111  USA
 24 * $/LicenseInfo$
 25 */
 26
 27#ifndef LL_LLTELEPORTHISTORY_H
 28#define LL_LLTELEPORTHISTORY_H
 29
 30#include "llsingleton.h" // for LLSingleton
 31
 32#include <vector>
 33#include <string>
 34#include <boost/function.hpp>
 35#include <boost/signals2.hpp>
 36#include "llteleporthistorystorage.h"
 37
 38
 39/**
 40 * An item of the teleport history.
 41 * 
 42 * Contains the location's global coordinates and its title.
 43 */
 44class LLTeleportHistoryItem
 45{
 46public:
 47	LLTeleportHistoryItem()
 48	{}
 49
 50	LLTeleportHistoryItem(std::string title, LLVector3d global_pos)
 51		: mTitle(title), mGlobalPos(global_pos)
 52	{}
 53
 54	/**
 55	 * @return title formatted according to the current value of the 
 56	 * NavBarShowCoordinates setting.
 57	 */
 58	const std::string& getTitle() const;
 59	
 60	std::string	mTitle;		// human-readable location title
 61	std::string mFullTitle; // human-readable location title including coordinates
 62	LLVector3d	mGlobalPos; // global position
 63	LLUUID		mRegionID;	// region ID for getting the region info 
 64};
 65
 66/**
 67 * Teleport history.
 68 * 
 69 * Along with the navigation bar "Back" and "Forward" buttons
 70 * implements web browser-like navigation functionality.
 71 * 
 72 * @see LLNavigationBar
 73 */
 74class LLTeleportHistory: public LLSingleton<LLTeleportHistory>
 75{
 76	LOG_CLASS(LLTeleportHistory);
 77
 78public:
 79	
 80	typedef std::vector<LLTeleportHistoryItem>	slurl_list_t;
 81	typedef boost::function<void()>				history_callback_t;
 82	typedef boost::signals2::signal<void()>		history_signal_t;
 83	
 84	LLTeleportHistory();
 85	~LLTeleportHistory();
 86
 87	/**
 88	 * Go back in the history.
 89	 */
 90	void					goBack() { goToItem(getCurrentItemIndex() - 1); }
 91	
 92	/**
 93	 * Go forward in the history.
 94	 */
 95	void					goForward() { goToItem(getCurrentItemIndex() + 1); }
 96	
 97	/**
 98	 * Go to specific item in the history.
 99	 * 
100	 * The item is specified by its index (starting from 0).
101	 */ 
102	void					goToItem(int idx);
103	
104	/**
105	 * @return history items.
106	 */
107	const slurl_list_t&		getItems() const { return mItems; }
108	void                    purgeItems();
109	/**
110	 * Is the history empty?
111	 * 
112	 * History containing single item is treated as empty
113	 * because the item points to the current location.
114	 */ 
115	bool					isEmpty() const { return mItems.size() <= 1; }
116	
117	/**
118	 * Get index of the current location in the history.
119	 */
120	int						getCurrentItemIndex() const { return mCurrentItem; }
121	/**
122	 * Set a callback to be called upon history changes.
123	 * 
124	 * Multiple callbacks can be set.
125	 */
126	boost::signals2::connection	setHistoryChangedCallback(history_callback_t cb);
127	
128	/**
129	 * Save history to a file so that we can restore it on startup.
130	 * 
131	 * @see load()
132	 */
133	void					dump() const;
134	/**
135	 * Process login complete event. Basically put current location into history
136	 */
137	void					handleLoginComplete();
138
139private:
140	
141	/**
142	 * Called by when a teleport fails.
143	 * 
144	 * Called via callback set on the LLViewerParcelMgr "teleport failed" signal.
145	 * 
146	 * @see mTeleportFailedConn
147	 */
148	void onTeleportFailed();
149
150	/**
151	 * Update current location.
152	 * 
153	 * @param new_pos Current agent global position. After local teleports we
154	 *                cannot rely on gAgent.getPositionGlobal(),
155	 *                so the new position gets passed explicitly.
156	 * 
157	 * Called when a teleport finishes.
158	 * Called via callback set on the LLViewerParcelMgr "teleport finished" signal.
159	 *
160	 * Takes mRequestedItem into consideration: if it's not -1
161	 * (i.e. user is teleporting to an arbitrary location, not to a history item)
162	 * we purge forward items and append a new one, making it current. Otherwise
163	 * we just modify mCurrentItem.
164	 * 
165	 * @see mRequestedItem
166	 * @see mGotInitialUpdate
167	 */
168	void					updateCurrentLocation(const LLVector3d& new_pos);
169	
170	/**
171	 * Invokes the "history changed" callback(s).
172	 */
173	void					onHistoryChanged();
174
175	/**
176	 * Format current agent location in a human-readable manner.
177	 * 
178	 * @param full whether to include coordinates
179	 * @param local_pos_override hack: see description of updateCurrentLocation()
180	 * @return
181	 */
182	static std::string		getCurrentLocationTitle(bool full, const LLVector3& local_pos_override);
183	
184	/**
185	 * Actually, the teleport history.
186	 */
187	slurl_list_t			mItems;
188	
189	/**
190	 * Current position within the history.
191	 */
192	int						mCurrentItem;
193	
194	/**
195	 * Requested position within the history.
196	 * 
197	 * When a teleport succeeds, this is checked by updateCurrentLocation() to tell
198	 * if this is a teleport within the history (mRequestedItem >=0) or not (-1).
199	 * 
200	 * Set by goToItem(); reset by onTeleportFailed() (if teleport fails).
201	 * 
202	 * @see goToItem()
203	 * @see updateCurrentLocation()
204	 */
205	int						mRequestedItem;
206	
207	/**
208	 * Have we received the initial location update?
209	 * 
210	 * @see updateCurrentLocation()
211	 */
212	bool					mGotInitialUpdate;
213	
214	LLTeleportHistoryStorage*	mTeleportHistoryStorage;
215
216	/**
217	 * Signal emitted when the history gets changed.
218	 * 
219	 * Invokes callbacks set with setHistoryChangedCallback().
220	 */
221	history_signal_t		mHistoryChangedSignal;
222	
223	/**
224	 * Teleport success notification connection.
225	 * 
226	 * Using this connection we get notified when a teleport finishes
227	 * or initial location update occurs.
228	 */
229	boost::signals2::connection	mTeleportFinishedConn;
230	
231	/**
232	 * Teleport failure notification connection.
233	 * 
234	 * Using this connection we get notified when a teleport fails.
235	 */
236	boost::signals2::connection	mTeleportFailedConn;
237};
238
239#endif