Context Navigation

source: OGRE/trunk/ogrenew/Dependencies/include/CEGUI/elements/CEGUIEditbox.h @ 657

Revision 657, 20.8 KB checked in by mattausch, 19 years ago (diff)
added ogre dependencies and patched ogre sources

Line
1	/************************************************************************
2	filename: CEGUIEditbox.h
3	created: 13/4/2004
4	author: Paul D Turner
5
6	purpose: Interface to base class for Editbox widget
7	*************************************************************************/
8	/*************************************************************************
9	Crazy Eddie's GUI System (http://www.cegui.org.uk)
10	Copyright (C)2004 - 2005 Paul D Turner (paul@cegui.org.uk)
11
12	This library is free software; you can redistribute it and/or
13	modify it under the terms of the GNU Lesser General Public
14	License as published by the Free Software Foundation; either
15	version 2.1 of the License, or (at your option) any later version.
16
17	This library is distributed in the hope that it will be useful,
18	but WITHOUT ANY WARRANTY; without even the implied warranty of
19	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20	Lesser General Public License for more details.
21
22	You should have received a copy of the GNU Lesser General Public
23	License along with this library; if not, write to the Free Software
24	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
25	*************************************************************************/
26	#ifndef _CEGUIEditbox_h_
27	#define _CEGUIEditbox_h_
28
29	#include "CEGUIBase.h"
30	#include "CEGUIWindow.h"
31	#include "elements/CEGUIEditboxProperties.h"
32
33
34	#if defined(_MSC_VER)
35	# pragma warning(push)
36	# pragma warning(disable : 4251)
37	#endif
38
39
40	// Start of CEGUI namespace section
41	namespace CEGUI
42	{
43	// forward declare implementation data type
44	struct RegexValidator;
45
46
47	/*!
48	\brief
49	Base class for an Editbox widget
50	*/
51	class CEGUIEXPORT Editbox : public Window
52	{
53	public:
54	static const String EventNamespace; //!< Namespace for global events
55
56
57	/*************************************************************************
58	Constants
59	*************************************************************************/
60	// default colours
61	static const argb_t DefaultNormalTextColour; //!< Colour applied to normal unselected text.
62	static const argb_t DefaultSelectedTextColour; //!< Colour applied to selected text.
63	static const argb_t DefaultNormalSelectionColour; //!< Colour applied to normal selection brush.
64	static const argb_t DefaultInactiveSelectionColour; //!< Colour applied to selection brush when widget is inactive.
65
66
67	/*************************************************************************
68	Event name constants
69	*************************************************************************/
70	static const String EventReadOnlyModeChanged; //!< The read-only mode for the edit box has been changed.
71	static const String EventMaskedRenderingModeChanged; //!< The masked rendering mode (password mode) has been changed.
72	static const String EventMaskCodePointChanged; //!< The code point (character) to use for masked text has been changed.
73	static const String EventValidationStringChanged; //!< The validation string has been changed.
74	static const String EventMaximumTextLengthChanged; //!< The maximum allowable string length has been changed.
75	static const String EventTextInvalidated; //!< Some operation has made the current text invalid with regards to the validation string.
76	static const String EventInvalidEntryAttempted; //!< The user attempted to modify the text in a way that would have made it invalid.
77	static const String EventCaratMoved; //!< The text carat (insert point) has changed.
78	static const String EventTextSelectionChanged; //!< The current text selection has changed.
79	static const String EventEditboxFull; //!< The number of characters in the edit box has reached the current maximum.
80	static const String EventTextAccepted; //!< The user has accepted the current text by pressing Return, Enter, or Tab.
81
82
83	/*************************************************************************
84	Accessor Functions
85	*************************************************************************/
86	/*!
87	\brief
88	return true if the Editbox has input focus.
89
90	\return
91	true if the Editbox has keyboard input focus, false if the Editbox does not have keyboard input focus.
92	*/
93	bool hasInputFocus(void) const;
94
95
96	/*!
97	\brief
98	return true if the Editbox is read-only.
99
100	\return
101	true if the Editbox is read only and can't be edited by the user, false if the Editbox is not
102	read only and may be edited by the user.
103	*/
104	bool isReadOnly(void) const {return d_readOnly;}
105
106
107	/*!
108	\brief
109	return true if the text for the Editbox will be rendered masked.
110
111	\return
112	true if the Editbox text will be rendered masked using the currently set mask code point, false if the Editbox
113	text will be rendered as plain text.
114	*/
115	bool isTextMasked(void) const {return d_maskText;}
116
117
118	/*!
119	\brief
120	return true if the Editbox text is valid given the currently set validation string.
121
122	\note
123	It is possible to programmatically set 'invalid' text for the Editbox by calling setText. This has certain
124	implications since if invalid text is set, whatever the user types into the box will be rejected when the input
125	is validated.
126
127	\note
128	Validation is performed by means of a regular expression. If the text matches the regex, the text is said to have passed
129	validation. If the text does not match with the regex then the text fails validation.
130
131	\return
132	true if the current Editbox text passes validation, false if the text does not pass validation.
133	*/
134	bool isTextValid(void) const;
135
136
137	/*!
138	\brief
139	return the currently set validation string
140
141	\note
142	Validation is performed by means of a regular expression. If the text matches the regex, the text is said to have passed
143	validation. If the text does not match with the regex then the text fails validation.
144
145	\return
146	String object containing the current validation regex data
147	*/
148	const String& getValidationString(void) const {return d_validationString;}
149
150
151	/*!
152	\brief
153	return the current position of the carat.
154
155	\return
156	Index of the insert carat relative to the start of the text.
157	*/
158	size_t getCaratIndex(void) const {return d_caratPos;}
159
160
161	/*!
162	\brief
163	return the current selection start point.
164
165	\return
166	Index of the selection start point relative to the start of the text. If no selection is defined this function returns
167	the position of the carat.
168	*/
169	size_t getSelectionStartIndex(void) const;
170
171
172	/*!
173	\brief
174	return the current selection end point.
175
176	\return
177	Index of the selection end point relative to the start of the text. If no selection is defined this function returns
178	the position of the carat.
179	*/
180	size_t getSelectionEndIndex(void) const;
181
182
183	/*!
184	\brief
185	return the length of the current selection (in code points / characters).
186
187	\return
188	Number of code points (or characters) contained within the currently defined selection.
189	*/
190	size_t getSelectionLength(void) const;
191
192
193	/*!
194	\brief
195	return the utf32 code point used when rendering masked text.
196
197	\return
198	utf32 code point value representing the Unicode code point that will be rendered instead of the Editbox text
199	when rendering in masked mode.
200	*/
201	utf32 getMaskCodePoint(void) const {return d_maskCodePoint;}
202
203
204	/*!
205	\brief
206	return the maximum text length set for this Editbox.
207
208	\return
209	The maximum number of code points (characters) that can be entered into this Editbox.
210
211	\note
212	Depending on the validation string set, the actual length of text that can be entered may be less than the value
213	returned here (it will never be more).
214	*/
215	size_t getMaxTextLength(void) const {return d_maxTextLen;}
216
217
218	/*!
219	\brief
220	return the currently set colour to be used for rendering Editbox text in the
221	normal, unselected state.
222
223	\return
224	colour value describing the ARGB colour that is currently set.
225	*/
226	colour getNormalTextColour(void) const {return d_normalTextColour;}
227
228
229	/*!
230	\brief
231	return the currently set colour to be used for rendering the Editbox text when within the
232	selected region.
233
234	\return
235	colour value describing the ARGB colour that is currently set.
236	*/
237	colour getSelectedTextColour(void) const {return d_selectTextColour;}
238
239
240	/*!
241	\brief
242	return the currently set colour to be used for rendering the Editbox selection highlight
243	when the Editbox is active.
244
245	\return
246	colour value describing the ARGB colour that is currently set.
247	*/
248	colour getNormalSelectBrushColour(void) const {return d_selectBrushColour;}
249
250
251	/*!
252	\brief
253	return the currently set colour to be used for rendering the Editbox selection highlight
254	when the Editbox is inactive.
255
256	\return
257	colour value describing the ARGB colour that is currently set.
258	*/
259	colour getInactiveSelectBrushColour(void) const {return d_inactiveSelectBrushColour;}
260
261
262	/*************************************************************************
263	Manipulators
264	*************************************************************************/
265	/*!
266	\brief
267	Specify whether the Editbox is read-only.
268
269	\param setting
270	true if the Editbox is read only and can't be edited by the user, false if the Editbox is not
271	read only and may be edited by the user.
272
273	\return
274	Nothing.
275	*/
276	void setReadOnly(bool setting);
277
278
279	/*!
280	\brief
281	Specify whether the text for the Editbox will be rendered masked.
282
283	\param setting
284	true if the Editbox text should be rendered masked using the currently set mask code point, false if the Editbox
285	text should be rendered as plain text.
286
287	\return
288	Nothing.
289	*/
290	void setTextMasked(bool setting);
291
292
293	/*!
294	\brief
295	Set the text validation string.
296
297	\note
298	Validation is performed by means of a regular expression. If the text matches the regex, the text is said to have passed
299	validation. If the text does not match with the regex then the text fails validation.
300
301	\param validation_string
302	String object containing the validation regex data to be used.
303
304	\return
305	Nothing.
306	*/
307	void setValidationString(const String& validation_string);
308
309
310	/*!
311	\brief
312	Set the current position of the carat.
313
314	\param carat_pos
315	New index for the insert carat relative to the start of the text. If the value specified is greater than the
316	number of characters in the Editbox, the carat is positioned at the end of the text.
317
318	\return
319	Nothing.
320	*/
321	void setCaratIndex(size_t carat_pos);
322
323
324	/*!
325	\brief
326	Define the current selection for the Editbox
327
328	\param start_pos
329	Index of the starting point for the selection. If this value is greater than the number of characters in the Editbox, the
330	selection start will be set to the end of the text.
331
332	\param end_pos
333	Index of the ending point for the selection. If this value is greater than the number of characters in the Editbox, the
334	selection end will be set to the end of the text.
335
336	\return
337	Nothing.
338	*/
339	void setSelection(size_t start_pos, size_t end_pos);
340
341
342	/*!
343	\brief
344	set the utf32 code point used when rendering masked text.
345
346	\param code_point
347	utf32 code point value representing the Unicode code point that should be rendered instead of the Editbox text
348	when rendering in masked mode.
349
350	\return
351	Nothing.
352	*/
353	void setMaskCodePoint(utf32 code_point);
354
355
356	/*!
357	\brief
358	set the maximum text length for this Editbox.
359
360	\param max_len
361	The maximum number of code points (characters) that can be entered into this Editbox.
362
363	\note
364	Depending on the validation string set, the actual length of text that can be entered may be less than the value
365	set here (it will never be more).
366
367	\return
368	Nothing.
369	*/
370	void setMaxTextLength(size_t max_len);
371
372
373	/*!
374	\brief
375	Set the colour to be used for rendering Editbox text in the normal, unselected state.
376
377	\param col
378	colour value describing the ARGB colour that is to be used.
379
380	\return
381	Nothing.
382	*/
383	void setNormalTextColour(const colour& col);
384
385
386	/*!
387	\brief
388	Set the colour to be used for rendering the Editbox text when within the
389	selected region.
390
391	\return
392	colour value describing the ARGB colour that is currently set.
393	*/
394	void setSelectedTextColour(const colour& col);
395
396
397	/*!
398	\brief
399	Set the colour to be used for rendering the Editbox selection highlight
400	when the Editbox is active.
401
402	\param col
403	colour value describing the ARGB colour that is to be used.
404
405	\return
406	Nothing.
407	*/
408	void setNormalSelectBrushColour(const colour& col);
409
410
411	/*!
412	\brief
413	Set the colour to be used for rendering the Editbox selection highlight
414	when the Editbox is inactive.
415
416	\param col
417	colour value describing the ARGB colour that is to be used.
418
419	\return
420	Nothing.
421	*/
422	void setInactiveSelectBrushColour(const colour& col);
423
424
425	/*************************************************************************
426	Construction / Destruction
427	*************************************************************************/
428	/*!
429	\brief
430	Constructor for Editbox class.
431	*/
432	Editbox(const String& type, const String& name);
433
434
435	/*!
436	\brief
437	Destructor for Editbox class.
438	*/
439	virtual ~Editbox(void);
440
441
442	protected:
443	/*************************************************************************
444	Implementation functions
445	*************************************************************************/
446	/*!
447	\brief
448	Add edit box specific events
449	*/
450	void addEditboxEvents(void);
451
452
453	/*!
454	\brief
455	Return the text code point index that is rendered closest to screen position \a pt.
456
457	\param pt
458	Point object describing a position on the screen in pixels.
459
460	\return
461	Code point index into the text that is rendered closest to screen position \a pt.
462	*/
463	virtual size_t getTextIndexFromPosition(const Point& pt) const = 0;
464
465
466	/*!
467	\brief
468	Clear the current selection setting
469	*/
470	void clearSelection(void);
471
472
473	/*!
474	\brief
475	Erase the currently selected text.
476
477	\param modify_text
478	when true, the actual text will be modified. When false, everything is done except erasing the characters.
479	*/
480	void eraseSelectedText(bool modify_text = true);
481
482
483	/*!
484	\brief
485	return true if the given string matches the validation regular expression.
486	*/
487	bool isStringValid(const String& str) const;
488
489
490
491	/*!
492	\brief
493	Processing for backspace key
494	*/
495	void handleBackspace(void);
496
497
498	/*!
499	\brief
500	Processing for Delete key
501	*/
502	void handleDelete(void);
503
504
505	/*!
506	\brief
507	Processing to move carat one character left
508	*/
509	void handleCharLeft(uint sysKeys);
510
511
512	/*!
513	\brief
514	Processing to move carat one word left
515	*/
516	void handleWordLeft(uint sysKeys);
517
518
519	/*!
520	\brief
521	Processing to move carat one character right
522	*/
523	void handleCharRight(uint sysKeys);
524
525
526	/*!
527	\brief
528	Processing to move carat one word right
529	*/
530	void handleWordRight(uint sysKeys);
531
532
533	/*!
534	\brief
535	Processing to move carat to the start of the text.
536	*/
537	void handleHome(uint sysKeys);
538
539
540	/*!
541	\brief
542	Processing to move carat to the end of the text
543	*/
544	void handleEnd(uint sysKeys);
545
546
547	/*!
548	\brief
549	Return whether this window was inherited from the given class name at some point in the inheritance heirarchy.
550
551	\param class_name
552	The class name that is to be checked.
553
554	\return
555	true if this window was inherited from \a class_name. false if not.
556	*/
557	virtual bool testClassName_impl(const String& class_name) const
558	{
559	if (class_name==(const utf8*)"Editbox") return true;
560	return Window::testClassName_impl(class_name);
561	}
562
563
564	/*************************************************************************
565	New event handlers
566	*************************************************************************/
567	/*!
568	\brief
569	Event fired internally when the read only state of the Editbox has been changed
570	*/
571	virtual void onReadOnlyChanged(WindowEventArgs& e);
572
573
574	/*!
575	\brief
576	Event fired internally when the masked rendering mode (password mode) has been changed
577	*/
578	virtual void onMaskedRenderingModeChanged(WindowEventArgs& e);
579
580
581	/*!
582	\brief
583	Event fired internally when the code point to use for masked rendering has been changed.
584	*/
585	virtual void onMaskCodePointChanged(WindowEventArgs& e);
586
587
588	/*!
589	\brief
590	Event fired internally when the validation string is changed.
591	*/
592	virtual void onValidationStringChanged(WindowEventArgs& e);
593
594
595	/*!
596	\brief
597	Event fired internally when the maximum text length for the edit box is changed.
598	*/
599	virtual void onMaximumTextLengthChanged(WindowEventArgs& e);
600
601
602	/*!
603	\brief
604	Event fired internally when something has caused the current text to now fail validation
605
606	This can be caused by changing the validation string or setting a maximum length that causes the
607	current text to be truncated.
608	*/
609	virtual void onTextInvalidatedEvent(WindowEventArgs& e);
610
611
612	/*!
613	\brief
614	Event fired internally when the user attempted to make a change to the edit box that would
615	have caused it to fail validation.
616	*/
617	virtual void onInvalidEntryAttempted(WindowEventArgs& e);
618
619
620	/*!
621	\brief
622	Event fired internally when the carat (insert point) position changes.
623	*/
624	virtual void onCaratMoved(WindowEventArgs& e);
625
626
627	/*!
628	\brief
629	Event fired internally when the current text selection changes.
630	*/
631	virtual void onTextSelectionChanged(WindowEventArgs& e);
632
633
634	/*!
635	\brief
636	Event fired internally when the edit box text has reached the set maximum length.
637	*/
638	virtual void onEditboxFullEvent(WindowEventArgs& e);
639
640
641	/*!
642	\brief
643	Event fired internally when the user accepts the edit box text by pressing Return, Enter, or Tab.
644	*/
645	virtual void onTextAcceptedEvent(WindowEventArgs& e);
646
647
648	/*************************************************************************
649	Overridden event handlers
650	*************************************************************************/
651	virtual void onMouseButtonDown(MouseEventArgs& e);
652	virtual void onMouseButtonUp(MouseEventArgs& e);
653	virtual void onMouseDoubleClicked(MouseEventArgs& e);
654	virtual void onMouseTripleClicked(MouseEventArgs& e);
655	virtual void onMouseMove(MouseEventArgs& e);
656	virtual void onCaptureLost(WindowEventArgs& e);
657	virtual void onCharacter(KeyEventArgs& e);
658	virtual void onKeyDown(KeyEventArgs& e);
659	virtual void onTextChanged(WindowEventArgs& e);
660
661
662	/*************************************************************************
663	Implementation data
664	*************************************************************************/
665	bool d_readOnly; //!< True if the editbox is in read-only mode
666	bool d_maskText; //!< True if the editbox text should be rendered masked.
667	utf32 d_maskCodePoint; //!< Code point to use when rendering masked text.
668	size_t d_maxTextLen; //!< Maximum number of characters for this Editbox.
669	size_t d_caratPos; //!< Position of the carat / insert-point.
670	size_t d_selectionStart; //!< Start of selection area.
671	size_t d_selectionEnd; //!< End of selection area.
672	String d_validationString; //!< Copy of validation reg-ex string.
673	RegexValidator* d_validator; //!< RegEx String used for validation of text.
674	bool d_dragging; //!< true when a selection is being dragged.
675	size_t d_dragAnchorIdx; //!< Selection index for drag selection anchor point.
676
677	// basic rendering colours
678	colour d_normalTextColour; //!< Text colour used normally.
679	colour d_selectTextColour; //!< Text colour used when text is highlighted
680	colour d_selectBrushColour; //!< Colour to apply to the selection brush.
681	colour d_inactiveSelectBrushColour; //!< Colour to apply to the selection brush when widget is inactive / read-only.
682
683
684	private:
685	/*************************************************************************
686	Static Properties for this class
687	*************************************************************************/
688	static EditboxProperties::ReadOnly d_readOnlyProperty;
689	static EditboxProperties::MaskText d_maskTextProperty;
690	static EditboxProperties::MaskCodepoint d_maskCodepointProperty;
691	static EditboxProperties::ValidationString d_validationStringProperty;
692	static EditboxProperties::CaratIndex d_caratIndexProperty;
693	static EditboxProperties::SelectionStart d_selectionStartProperty;
694	static EditboxProperties::SelectionLength d_selectionLengthProperty;
695	static EditboxProperties::MaxTextLength d_maxTextLengthProperty;
696	static EditboxProperties::NormalTextColour d_normalTextColourProperty;
697	static EditboxProperties::SelectedTextColour d_selectedTextColourProperty;
698	static EditboxProperties::ActiveSelectionColour d_activeSelectionColourProperty;
699	static EditboxProperties::InactiveSelectionColour d_inactiveSelectionColourProperty;
700
701
702	/*************************************************************************
703	Private methods
704	*************************************************************************/
705	void addEditboxProperties(void);
706	};
707
708	} // End of CEGUI namespace section
709
710
711	#if defined(_MSC_VER)
712	# pragma warning(pop)
713	#endif
714
715	#endif // end of guard _CEGUIEditbox_h_

Note: See TracBrowser for help on using the repository browser.

Download in other formats: