/indra/llui/lluictrl.h

  1/** 
  2 * @file lluictrl.h
  3 * @author James Cook, Richard Nelson, Tom Yedwab
  4 * @brief Abstract base class for UI controls
  5 *
  6 * $LicenseInfo:firstyear=2001&license=viewerlgpl$
  7 * Second Life Viewer Source Code
  8 * Copyright (C) 2010, Linden Research, Inc.
  9 * 
 10 * This library is free software; you can redistribute it and/or
 11 * modify it under the terms of the GNU Lesser General Public
 12 * License as published by the Free Software Foundation;
 13 * version 2.1 of the License only.
 14 * 
 15 * This library is distributed in the hope that it will be useful,
 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 18 * Lesser General Public License for more details.
 19 * 
 20 * You should have received a copy of the GNU Lesser General Public
 21 * License along with this library; if not, write to the Free Software
 22 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 23 * 
 24 * Linden Research, Inc., 945 Battery Street, San Francisco, CA  94111  USA
 25 * $/LicenseInfo$
 26 */
 27
 28#ifndef LL_LLUICTRL_H
 29#define LL_LLUICTRL_H
 30
 31//#include "llboost.h"
 32#include "llrect.h"
 33#include "llsd.h"
 34#include <boost/function.hpp>
 35#include <boost/signals2.hpp>
 36
 37#include "llinitparam.h"
 38#include "llview.h"
 39#include "llviewmodel.h"		// *TODO move dependency to .cpp file
 40
 41const BOOL TAKE_FOCUS_YES = TRUE;
 42const BOOL TAKE_FOCUS_NO  = FALSE;
 43
 44class LLUICtrl
 45	: public LLView, public boost::signals2::trackable
 46{
 47public:
 48	typedef boost::function<void (LLUICtrl* ctrl, const LLSD& param)> commit_callback_t;
 49	typedef boost::signals2::signal<void (LLUICtrl* ctrl, const LLSD& param)> commit_signal_t;
 50	// *TODO: add xml support for this type of signal in the future
 51	typedef boost::signals2::signal<void (LLUICtrl* ctrl, S32 x, S32 y, MASK mask)> mouse_signal_t;
 52	
 53	typedef boost::function<bool (LLUICtrl* ctrl, const LLSD& param)> enable_callback_t;
 54	typedef boost::signals2::signal<bool (LLUICtrl* ctrl, const LLSD& param), boost_boolean_combiner> enable_signal_t;
 55	
 56	struct CallbackParam : public LLInitParam::Block<CallbackParam>
 57	{
 58		Ignored					name;
 59
 60		Optional<std::string>	function_name;
 61		Optional<LLSD>			parameter;
 62
 63		Optional<std::string>	control_name;
 64		
 65		CallbackParam();
 66	};
 67
 68	struct CommitCallbackParam : public LLInitParam::Block<CommitCallbackParam, CallbackParam >
 69	{
 70		Optional<commit_callback_t> function;
 71	};
 72
 73	// also used for visible callbacks
 74	struct EnableCallbackParam : public LLInitParam::Block<EnableCallbackParam, CallbackParam >
 75	{
 76		Optional<enable_callback_t> function;
 77	};
 78		
 79	struct EnableControls : public LLInitParam::ChoiceBlock<EnableControls>
 80	{
 81		Alternative<std::string> enabled;
 82		Alternative<std::string> disabled;
 83		
 84		EnableControls();
 85	};	
 86	struct ControlVisibility : public LLInitParam::ChoiceBlock<ControlVisibility>
 87	{
 88		Alternative<std::string> visible;
 89		Alternative<std::string> invisible;
 90
 91		ControlVisibility();
 92	};	
 93	struct Params : public LLInitParam::Block<Params, LLView::Params>
 94	{
 95		Optional<std::string>			label;
 96		Optional<bool>					tab_stop,
 97										chrome,
 98										requests_front;
 99		Optional<LLSD>					initial_value;
100
101		Optional<CommitCallbackParam>	init_callback,
102										commit_callback;
103		Optional<EnableCallbackParam>	validate_callback;
104		
105		Optional<CommitCallbackParam>	mouseenter_callback,
106										mouseleave_callback;
107		
108		Optional<std::string>			control_name;
109		Optional<EnableControls>		enabled_controls;
110		Optional<ControlVisibility>		controls_visibility;
111		
112		// font params
113		Optional<const LLFontGL*>		font;
114		Optional<LLFontGL::HAlign>		font_halign;
115		Optional<LLFontGL::VAlign>		font_valign;
116
117		// cruft from LLXMLNode implementation
118		Ignored							type,
119										length;
120
121		Params();
122	};
123
124	enum ETypeTransparency
125	{
126		TT_DEFAULT,
127		TT_ACTIVE,		// focused floater
128		TT_INACTIVE,	// other floaters
129		TT_FADING,		// fading toast
130	};
131	/*virtual*/ ~LLUICtrl();
132
133	void initFromParams(const Params& p);
134protected:
135	friend class LLUICtrlFactory;
136	static const Params& getDefaultParams();
137	LLUICtrl(const Params& p = getDefaultParams(),
138             const LLViewModelPtr& viewmodel=LLViewModelPtr(new LLViewModel));
139	
140	commit_signal_t::slot_type initCommitCallback(const CommitCallbackParam& cb);
141	enable_signal_t::slot_type initEnableCallback(const EnableCallbackParam& cb);
142
143	// We need this virtual so we can override it with derived versions
144	virtual LLViewModel* getViewModel() const;
145    // We shouldn't ever need to set this directly
146    //virtual void    setViewModel(const LLViewModelPtr&);
147
148	virtual BOOL	postBuild();
149	
150public:
151	// LLView interface
152	/*virtual*/ BOOL	setLabelArg( const std::string& key, const LLStringExplicit& text );
153	/*virtual*/ BOOL	isCtrl() const;
154	/*virtual*/ void	onMouseEnter(S32 x, S32 y, MASK mask);
155	/*virtual*/ void	onMouseLeave(S32 x, S32 y, MASK mask);
156	/*virtual*/ BOOL	canFocusChildren() const;
157	/*virtual*/ BOOL 	handleMouseDown(S32 x, S32 y, MASK mask);
158	/*virtual*/ BOOL 	handleMouseUp(S32 x, S32 y, MASK mask);
159	/*virtual*/ BOOL	handleRightMouseDown(S32 x, S32 y, MASK mask);
160	/*virtual*/ BOOL	handleRightMouseUp(S32 x, S32 y, MASK mask);
161	/*virtual*/ BOOL	handleDoubleClick(S32 x, S32 y, MASK mask);
162
163	// From LLFocusableElement
164	/*virtual*/ void	setFocus( BOOL b );
165	/*virtual*/ BOOL	hasFocus() const;
166	
167	// New virtuals
168
169	// Return NULL by default (overrride if the class has the appropriate interface)
170	virtual class LLCtrlSelectionInterface* getSelectionInterface();
171	virtual class LLCtrlListInterface* getListInterface();
172	virtual class LLCtrlScrollInterface* getScrollInterface();
173
174	bool setControlValue(const LLSD& value);
175	void setControlVariable(LLControlVariable* control);
176	virtual void setControlName(const std::string& control, LLView *context = NULL);
177	
178	LLControlVariable* getControlVariable() { return mControlVariable; } 
179	
180	void setEnabledControlVariable(LLControlVariable* control);
181	void setDisabledControlVariable(LLControlVariable* control);
182	void setMakeVisibleControlVariable(LLControlVariable* control);
183	void setMakeInvisibleControlVariable(LLControlVariable* control);
184
185	virtual void	setTentative(BOOL b);
186	virtual BOOL	getTentative() const;
187	virtual void	setValue(const LLSD& value);
188	virtual LLSD	getValue() const;
189    /// When two widgets are displaying the same data (e.g. during a skin
190    /// change), share their ViewModel.
191    virtual void    shareViewModelFrom(const LLUICtrl& other);
192
193	virtual BOOL	setTextArg(  const std::string& key, const LLStringExplicit& text );
194	virtual void	setIsChrome(BOOL is_chrome);
195
196	virtual BOOL	acceptsTextInput() const; // Defaults to false
197
198	// A control is dirty if the user has modified its value.
199	// Editable controls should override this.
200	virtual BOOL	isDirty() const; // Defauls to false
201	virtual void	resetDirty(); //Defaults to no-op
202	
203	// Call appropriate callback
204	virtual void	onCommit();
205	
206	// Default to no-op:
207	virtual void	onTabInto();
208
209	// Clear any user-provided input (text in a text editor, checked checkbox,
210	// selected radio button, etc.).  Defaults to no-op.
211	virtual void	clear();
212
213	virtual void	setColor(const LLColor4& color);
214
215	F32 			getCurrentTransparency();
216
217	void				setTransparencyType(ETypeTransparency type);
218	ETypeTransparency	getTransparencyType() const {return mTransparencyType;}
219
220	BOOL	focusNextItem(BOOL text_entry_only);
221	BOOL	focusPrevItem(BOOL text_entry_only);
222	BOOL 	focusFirstItem(BOOL prefer_text_fields = FALSE, BOOL focus_flash = TRUE );
223	BOOL	focusLastItem(BOOL prefer_text_fields = FALSE);
224
225	// Non Virtuals
226	LLHandle<LLUICtrl> getHandle() const { return getDerivedHandle<LLUICtrl>(); }
227	BOOL			getIsChrome() const;
228	
229	void			setTabStop( BOOL b );
230	BOOL			hasTabStop() const;
231
232	LLUICtrl*		getParentUICtrl() const;
233
234	// return true if help topic found by crawling through parents -
235	// topic then put in help_topic_out
236	bool                    findHelpTopic(std::string& help_topic_out);
237
238	boost::signals2::connection setCommitCallback(const CommitCallbackParam& cb);
239	boost::signals2::connection setValidateCallback(const EnableCallbackParam& cb);
240
241	boost::signals2::connection setCommitCallback( const commit_signal_t::slot_type& cb );
242	boost::signals2::connection setValidateCallback( const enable_signal_t::slot_type& cb );
243
244	boost::signals2::connection setMouseEnterCallback( const commit_signal_t::slot_type& cb );
245	boost::signals2::connection setMouseLeaveCallback( const commit_signal_t::slot_type& cb );
246	
247	boost::signals2::connection setMouseDownCallback( const mouse_signal_t::slot_type& cb );
248	boost::signals2::connection setMouseUpCallback( const mouse_signal_t::slot_type& cb );
249	boost::signals2::connection setRightMouseDownCallback( const mouse_signal_t::slot_type& cb );
250	boost::signals2::connection setRightMouseUpCallback( const mouse_signal_t::slot_type& cb );
251	
252	boost::signals2::connection setDoubleClickCallback( const mouse_signal_t::slot_type& cb );
253
254	// *TODO: Deprecate; for backwards compatability only:
255	boost::signals2::connection setCommitCallback( boost::function<void (LLUICtrl*,void*)> cb, void* data);	
256	boost::signals2::connection setValidateBeforeCommit( boost::function<bool (const LLSD& data)> cb );
257
258	LLUICtrl* findRootMostFocusRoot();
259
260	class LLTextInputFilter : public LLQueryFilter, public LLSingleton<LLTextInputFilter>
261	{
262		/*virtual*/ filterResult_t operator() (const LLView* const view, const viewList_t & children) const 
263		{
264			return filterResult_t(view->isCtrl() && static_cast<const LLUICtrl *>(view)->acceptsTextInput(), TRUE);
265		}
266	};
267	
268	template <typename F, typename DERIVED> class CallbackRegistry : public LLRegistrySingleton<std::string, F, DERIVED >
269	{};	
270
271	class CommitCallbackRegistry : public CallbackRegistry<commit_callback_t, CommitCallbackRegistry>{};
272	// the enable callback registry is also used for visiblity callbacks
273	class EnableCallbackRegistry : public CallbackRegistry<enable_callback_t, EnableCallbackRegistry>{};
274		
275protected:
276
277	static bool controlListener(const LLSD& newvalue, LLHandle<LLUICtrl> handle, std::string type);
278
279	commit_signal_t*		mCommitSignal;
280	enable_signal_t*		mValidateSignal;
281
282	commit_signal_t*		mMouseEnterSignal;
283	commit_signal_t*		mMouseLeaveSignal;
284	
285	mouse_signal_t*		mMouseDownSignal;
286	mouse_signal_t*		mMouseUpSignal;
287	mouse_signal_t*		mRightMouseDownSignal;
288	mouse_signal_t*		mRightMouseUpSignal;
289
290	mouse_signal_t*		mDoubleClickSignal;
291	
292    LLViewModelPtr  mViewModel;
293
294	LLControlVariable* mControlVariable;
295	boost::signals2::connection mControlConnection;
296	LLControlVariable* mEnabledControlVariable;
297	boost::signals2::connection mEnabledControlConnection;
298	LLControlVariable* mDisabledControlVariable;
299	boost::signals2::connection mDisabledControlConnection;
300	LLControlVariable* mMakeVisibleControlVariable;
301	boost::signals2::connection mMakeVisibleControlConnection;
302	LLControlVariable* mMakeInvisibleControlVariable;
303	boost::signals2::connection mMakeInvisibleControlConnection;
304
305	static F32 sActiveControlTransparency;
306	static F32 sInactiveControlTransparency;
307	
308	virtual void addInfo(LLSD & info);
309	
310private:
311
312	BOOL			mIsChrome;
313	BOOL			mRequestsFront;
314	BOOL			mTabStop;
315	BOOL			mTentative;
316
317	ETypeTransparency mTransparencyType;
318
319	class DefaultTabGroupFirstSorter;
320};
321
322// Build time optimization, generate once in .cpp file
323#ifndef LLUICTRL_CPP
324extern template class LLUICtrl* LLView::getChild<class LLUICtrl>(
325	const std::string& name, BOOL recurse) const;
326#endif
327
328#endif  // LL_LLUICTRL_H