Context Navigation

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

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

Line
1	/************************************************************************
2	filename: CEGUIMultiLineEditbox.h
3	created: 30/6/2004
4	author: Paul D Turner
5
6	purpose: Interface to the Multi-lien edit box base class.
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 _CEGUIMultiLineEditbox_h_
27	#define _CEGUIMultiLineEditbox_h_
28
29	#include "CEGUIBase.h"
30	#include "CEGUIWindow.h"
31	#include "CEGUIFont.h"
32	#include "elements/CEGUIMultiLineEditboxProperties.h"
33
34	#include <vector>
35
36
37	#if defined(_MSC_VER)
38	# pragma warning(push)
39	# pragma warning(disable : 4251)
40	#endif
41
42
43	// Start of CEGUI namespace section
44	namespace CEGUI
45	{
46	/*!
47	\brief
48	Base class for the multi-line edit box widget.
49	*/
50	class CEGUIEXPORT MultiLineEditbox : public Window
51	{
52	public:
53	static const String EventNamespace; //!< Namespace for global events
54
55
56	/*************************************************************************
57	Constants
58	*************************************************************************/
59	// event names
60	static const String EventReadOnlyModeChanged; //!< The read-only mode for the edit box has been changed.
61	static const String EventWordWrapModeChanged; //!< The word wrap mode of the text box has been changed.
62	static const String EventMaximumTextLengthChanged; //!< The maximum allowable string length has been changed.
63	static const String EventCaratMoved; //!< The text carat (insert point) has changed.
64	static const String EventTextSelectionChanged; //!< The current text selection has changed.
65	static const String EventEditboxFull; //!< The number of characters in the edit box has reached the current maximum.
66	static const String EventVertScrollbarModeChanged; //!< Event triggered when the vertical scroll bar 'force' setting changes.
67	static const String EventHorzScrollbarModeChanged; //!< Event triggered when the horizontal scroll bar 'force' setting changes.
68
69	// default colours
70	static const argb_t DefaultNormalTextColour; //!< Colour applied to normal unselected text.
71	static const argb_t DefaultSelectedTextColour; //!< Colour applied to selected text.
72	static const argb_t DefaultNormalSelectionColour; //!< Colour applied to normal selection brush.
73	static const argb_t DefaultInactiveSelectionColour; //!< Colour applied to selection brush when widget is inactive.
74
75
76	/*************************************************************************
77	Accessor Functions
78	*************************************************************************/
79	/*!
80	\brief
81	return true if the edit box has input focus.
82
83	\return
84	- true if the edit box has keyboard input focus.
85	- false if the edit box does not have keyboard input focus.
86	*/
87	bool hasInputFocus(void) const;
88
89
90	/*!
91	\brief
92	return true if the edit box is read-only.
93
94	\return
95	- true if the edit box is read only and can't be edited by the user.
96	- false if the edit box is not read only and may be edited by the user.
97	*/
98	bool isReadOnly(void) const {return d_readOnly;}
99
100
101	/*!
102	\brief
103	return the current position of the carat.
104
105	\return
106	Index of the insert carat relative to the start of the text.
107	*/
108	size_t getCaratIndex(void) const {return d_caratPos;}
109
110
111	/*!
112	\brief
113	return the current selection start point.
114
115	\return
116	Index of the selection start point relative to the start of the text. If no selection is defined this function returns
117	the position of the carat.
118	*/
119	size_t getSelectionStartIndex(void) const;
120
121
122	/*!
123	\brief
124	return the current selection end point.
125
126	\return
127	Index of the selection end point relative to the start of the text. If no selection is defined this function returns
128	the position of the carat.
129	*/
130	size_t getSelectionEndIndex(void) const;
131
132
133	/*!
134	\brief
135	return the length of the current selection (in code points / characters).
136
137	\return
138	Number of code points (or characters) contained within the currently defined selection.
139	*/
140	size_t getSelectionLength(void) const;
141
142
143	/*!
144	\brief
145	return the maximum text length set for this edit box.
146
147	\return
148	The maximum number of code points (characters) that can be entered into this edit box.
149	*/
150	size_t getMaxTextLength(void) const {return d_maxTextLen;}
151
152
153	/*!
154	\brief
155	return the currently set colour to be used for rendering edit box text in the
156	normal, unselected state.
157
158	\return
159	colour value describing the ARGB colour that is currently set.
160	*/
161	colour getNormalTextColour(void) const {return d_normalTextColour;}
162
163
164	/*!
165	\brief
166	return the currently set colour to be used for rendering the edit box text when within the
167	selected region.
168
169	\return
170	colour value describing the ARGB colour that is currently set.
171	*/
172	colour getSelectedTextColour(void) const {return d_selectTextColour;}
173
174
175	/*!
176	\brief
177	return the currently set colour to be used for rendering the edit box selection highlight
178	when the edit box is active.
179
180	\return
181	colour value describing the ARGB colour that is currently set.
182	*/
183	colour getNormalSelectBrushColour(void) const {return d_selectBrushColour;}
184
185
186	/*!
187	\brief
188	return the currently set colour to be used for rendering the edit box selection highlight
189	when the edit box is inactive.
190
191	\return
192	colour value describing the ARGB colour that is currently set.
193	*/
194	colour getInactiveSelectBrushColour(void) const {return d_inactiveSelectBrushColour;}
195
196
197	/*!
198	\brief
199	Return whether the text in the edit box will be word-wrapped.
200
201	\return
202	- true if the text will be word-wrapped at the edges of the widget frame.
203	- false if text will not be word-wrapped (a scroll bar will be used to access long text lines).
204	*/
205	bool isWordWrapped(void) const;
206
207
208	/*************************************************************************
209	Manipulators
210	*************************************************************************/
211	/*!
212	\brief
213	Initialise the Window based object ready for use.
214
215	\note
216	This must be called for every window created. Normally this is handled automatically by the WindowFactory for each Window type.
217
218	\return
219	Nothing
220	*/
221	virtual void initialise(void);
222
223
224	/*!
225	\brief
226	Specify whether the edit box is read-only.
227
228	\param setting
229	- true if the edit box is read only and can't be edited by the user.
230	- false if the edit box is not read only and may be edited by the user.
231
232	\return
233	Nothing.
234	*/
235	void setReadOnly(bool setting);
236
237
238	/*!
239	\brief
240	Set the current position of the carat.
241
242	\param carat_pos
243	New index for the insert carat relative to the start of the text. If the value specified is greater than the
244	number of characters in the edit box, the carat is positioned at the end of the text.
245
246	\return
247	Nothing.
248	*/
249	void setCaratIndex(size_t carat_pos);
250
251
252	/*!
253	\brief
254	Define the current selection for the edit box
255
256	\param start_pos
257	Index of the starting point for the selection. If this value is greater than the number of characters in the edit box, the
258	selection start will be set to the end of the text.
259
260	\param end_pos
261	Index of the ending point for the selection. If this value is greater than the number of characters in the edit box, the
262	selection start will be set to the end of the text.
263
264	\return
265	Nothing.
266	*/
267	void setSelection(size_t start_pos, size_t end_pos);
268
269
270	/*!
271	\brief
272	set the maximum text length for this edit box.
273
274	\param max_len
275	The maximum number of code points (characters) that can be entered into this Editbox.
276
277	\return
278	Nothing.
279	*/
280	void setMaxTextLength(size_t max_len);
281
282
283	/*!
284	\brief
285	Set the colour to be used for rendering edit box text in the normal, unselected state.
286
287	\param col
288	colour value describing the ARGB colour that is to be used.
289
290	\return
291	Nothing.
292	*/
293	void setNormalTextColour(const colour& col);
294
295
296	/*!
297	\brief
298	Set the colour to be used for rendering the edit box text when within the
299	selected region.
300
301	\return
302	colour value describing the ARGB colour that is currently set.
303	*/
304	void setSelectedTextColour(const colour& col);
305
306
307	/*!
308	\brief
309	Set the colour to be used for rendering the edit box selection highlight
310	when the edit box is active.
311
312	\param col
313	colour value describing the ARGB colour that is to be used.
314
315	\return
316	Nothing.
317	*/
318	void setNormalSelectBrushColour(const colour& col);
319
320
321	/*!
322	\brief
323	Set the colour to be used for rendering the edit box selection highlight
324	when the edit box is inactive.
325
326	\param col
327	colour value describing the ARGB colour that is to be used.
328
329	\return
330	Nothing.
331	*/
332	void setInactiveSelectBrushColour(const colour& col);
333
334
335	/*!
336	\brief
337	Scroll the view so that the current carat position is visible.
338	*/
339	void ensureCaratIsVisible(void);
340
341
342	/*!
343	\brief
344	Set whether the text will be word wrapped or not.
345
346	\param setting
347	- true if the text should word-wrap at the edges of the text box.
348	- false if the text should not wrap, but a scroll bar should be used.
349
350	\return
351	Nothing.
352	*/
353	void setWordWrapping(bool setting);
354
355
356	/*************************************************************************
357	Construction and Destruction
358	*************************************************************************/
359	/*!
360	\brief
361	Constructor for the MultiLineEditbox base class.
362	*/
363	MultiLineEditbox(const String& type, const String& name);
364
365
366	/*!
367	\brief
368	Destructor for the MultiLineEditbox base class.
369	*/
370	virtual ~MultiLineEditbox(void);
371
372
373	protected:
374	/*************************************************************************
375	Implementation Methods (abstract)
376	*************************************************************************/
377	/*!
378	\brief
379	Return a Rect object describing, in un-clipped pixels, the window relative area
380	that the text should be rendered in to.
381
382	\return
383	Rect object describing the area of the Window to be used for rendering text.
384	*/
385	virtual Rect getTextRenderArea(void) const = 0;
386
387
388	/*!
389	\brief
390	create and return a pointer to a Scrollbar widget for use as vertical scroll bar
391
392	\return
393	Pointer to a Scrollbar to be used for scrolling vertically.
394	*/
395	virtual Scrollbar* createVertScrollbar(void) const = 0;
396
397
398	/*!
399	\brief
400	create and return a pointer to a Scrollbar widget for use as horizontal scroll bar
401
402	\return
403	Pointer to a Scrollbar to be used for scrolling horizontally.
404	*/
405	virtual Scrollbar* createHorzScrollbar(void) const = 0;
406
407
408	/*!
409	\brief
410	Setup size and position for the component widgets attached to this Editbox
411
412	\return
413	Nothing.
414	*/
415	virtual void layoutComponentWidgets() = 0;
416
417
418	/*!
419	\brief
420	Perform rendering of the widget control frame and other 'static' areas. This
421	method should not render the actual text. Note that the text will be rendered
422	to layer 4 and the selection brush to layer 3, other layers can be used for
423	rendering imagery behind and infront of the text & selection..
424
425	\param z
426	Z co-ordinate for layer 0.
427
428	\return
429	Nothing.
430	*/
431	virtual void renderEditboxBaseImagery(float z) = 0;
432
433
434	/*!
435	\brief
436	Render the carat.
437
438	\return
439	Nothing
440	*/
441	virtual void renderCarat(float baseX, float baseY, const Rect& clipper) = 0;
442
443
444	/*************************************************************************
445	Implementation Methods
446	*************************************************************************/
447	/*!
448	\brief
449	Add multi-line edit box specific events
450	*/
451	void addMultiLineEditboxEvents(void);
452
453
454	/*!
455	\brief
456	Render text lines.
457	*/
458	void renderTextLines(const Rect& dest_area, const Rect& clipper) const;
459
460
461	/*!
462	\brief
463	Format the text into lines as needed by the current formatting options.
464	*/
465	void formatText(void);
466
467
468	/*!
469	\brief
470	Return the length of the next token in String \a text starting at index \a start_idx.
471
472	\note
473	Any single whitespace character is one token, any group of other characters is a token.
474
475	\return
476	The code point length of the token.
477	*/
478	size_t getNextTokenLength(const String& text, size_t start_idx) const;
479
480
481	/*!
482	\brief
483	Perform the actual rendering for this Window.
484
485	\param z
486	float value specifying the base Z co-ordinate that should be used when rendering
487
488	\return
489	Nothing
490	*/
491	virtual void drawSelf(float z);
492
493
494	/*!
495	\brief
496	display required integrated scroll bars according to current state of the edit box and update their values.
497	*/
498	void configureScrollbars(void);
499
500
501	/*!
502	\brief
503	Return the text code point index that is rendered closest to screen position \a pt.
504
505	\param pt
506	Point object describing a position on the screen in pixels.
507
508	\return
509	Code point index into the text that is rendered closest to screen position \a pt.
510	*/
511	size_t getTextIndexFromPosition(const Point& pt) const;
512
513
514	/*!
515	\brief
516	Return the line number a given index falls on with the current formatting. Will return last line
517	if index is out of range.
518	*/
519	size_t getLineNumberFromIndex(size_t index) const;
520
521
522	/*!
523	\brief
524	Clear the current selection setting
525	*/
526	void clearSelection(void);
527
528
529	/*!
530	\brief
531	Erase the currently selected text.
532
533	\param modify_text
534	when true, the actual text will be modified. When false, everything is done except erasing the characters.
535	*/
536	void eraseSelectedText(bool modify_text = true);
537
538
539	/*!
540	\brief
541	Processing for backspace key
542	*/
543	void handleBackspace(void);
544
545
546	/*!
547	\brief
548	Processing for Delete key
549	*/
550	void handleDelete(void);
551
552
553	/*!
554	\brief
555	Processing to move carat one character left
556	*/
557	void handleCharLeft(uint sysKeys);
558
559
560	/*!
561	\brief
562	Processing to move carat one word left
563	*/
564	void handleWordLeft(uint sysKeys);
565
566
567	/*!
568	\brief
569	Processing to move carat one character right
570	*/
571	void handleCharRight(uint sysKeys);
572
573
574	/*!
575	\brief
576	Processing to move carat one word right
577	*/
578	void handleWordRight(uint sysKeys);
579
580
581	/*!
582	\brief
583	Processing to move carat to the start of the text.
584	*/
585	void handleDocHome(uint sysKeys);
586
587
588	/*!
589	\brief
590	Processing to move carat to the end of the text
591	*/
592	void handleDocEnd(uint sysKeys);
593
594
595	/*!
596	\brief
597	Processing to move carat to the start of the current line.
598	*/
599	void handleLineHome(uint sysKeys);
600
601
602	/*!
603	\brief
604	Processing to move carat to the end of the current line
605	*/
606	void handleLineEnd(uint sysKeys);
607
608
609	/*!
610	\brief
611	Processing to move carat up a line.
612	*/
613	void handleLineUp(uint sysKeys);
614
615
616	/*!
617	\brief
618	Processing to move carat down a line.
619	*/
620	void handleLineDown(uint sysKeys);
621
622
623	/*!
624	\brief
625	Processing to insert a new line / paragraph.
626	*/
627	void handleNewLine(uint sysKeys);
628
629
630	/*!
631	\brief
632	Return whether this window was inherited from the given class name at some point in the inheritance heirarchy.
633
634	\param class_name
635	The class name that is to be checked.
636
637	\return
638	true if this window was inherited from \a class_name. false if not.
639	*/
640	virtual bool testClassName_impl(const String& class_name) const
641	{
642	if (class_name==(const utf8*)"MultiLineEditBox") return true;
643	return Window::testClassName_impl(class_name);
644	}
645
646	/*************************************************************************
647	New event handlers
648	*************************************************************************/
649	/*!
650	\brief
651	Handler called when the read-only state of the edit box changes
652	*/
653	void onReadOnlyChanged(WindowEventArgs& e);
654
655
656	/*!
657	\brief
658	Handler called when the word wrap mode for the the edit box changes
659	*/
660	void onWordWrapModeChanged(WindowEventArgs& e);
661
662
663	/*!
664	\brief
665	Handler called when the maximum text length for the edit box changes
666	*/
667	void onMaximumTextLengthChanged(WindowEventArgs& e);
668
669
670	/*!
671	\brief
672	Handler called when the carat moves.
673	*/
674	void onCaratMoved(WindowEventArgs& e);
675
676
677	/*!
678	\brief
679	Handler called when the text selection changes
680	*/
681	void onTextSelectionChanged(WindowEventArgs& e);
682
683
684	/*!
685	\brief
686	Handler called when the edit box is full
687	*/
688	void onEditboxFullEvent(WindowEventArgs& e);
689
690
691	/*!
692	\brief
693	Handler called when the 'always show' setting for the vertical scroll bar changes.
694	*/
695	void onVertScrollbarModeChanged(WindowEventArgs& e);
696
697
698	/*!
699	\brief
700	Handler called when 'always show' setting for the horizontal scroll bar changes.
701	*/
702	void onHorzScrollbarModeChanged(WindowEventArgs& e);
703
704
705	/*************************************************************************
706	Overridden event handlers
707	*************************************************************************/
708	virtual void onMouseButtonDown(MouseEventArgs& e);
709	virtual void onMouseButtonUp(MouseEventArgs& e);
710	virtual void onMouseDoubleClicked(MouseEventArgs& e);
711	virtual void onMouseTripleClicked(MouseEventArgs& e);
712	virtual void onMouseMove(MouseEventArgs& e);
713	virtual void onCaptureLost(WindowEventArgs& e);
714	virtual void onCharacter(KeyEventArgs& e);
715	virtual void onKeyDown(KeyEventArgs& e);
716	virtual void onTextChanged(WindowEventArgs& e);
717	virtual void onSized(WindowEventArgs& e);
718	virtual void onMouseWheel(MouseEventArgs& e);
719
720
721	/*************************************************************************
722	Implementation struct
723	*************************************************************************/
724	/*!
725	\brief
726	struct used to store information about a formatted line within the
727	paragraph.
728	*/
729	struct LineInfo
730	{
731	size_t d_startIdx; //!< Starting index for this line.
732	size_t d_length; //!< Code point length of this line.
733	float d_extent; //!< Rendered extent of this line.
734	};
735
736
737	/*************************************************************************
738	Implementation data
739	*************************************************************************/
740	bool d_readOnly; //!< true if the edit box is in read-only mode
741	size_t d_maxTextLen; //!< Maximum number of characters for this Editbox.
742	size_t d_caratPos; //!< Position of the carat / insert-point.
743	size_t d_selectionStart; //!< Start of selection area.
744	size_t d_selectionEnd; //!< End of selection area.
745	bool d_dragging; //!< true when a selection is being dragged.
746	size_t d_dragAnchorIdx; //!< Selection index for drag selection anchor point.
747
748	typedef std::vector<LineInfo> LineList; //!< Type for collection of LineInfos.
749	static String d_lineBreakChars; //!< Holds what we consider to be line break characters.
750	bool d_wordWrap; //!< true when formatting uses word-wrapping.
751	LineList d_lines; //!< Holds the lines for the current formatting.
752	float d_widestExtent; //!< Holds the extent of the widest line as calculated in the last formatting pass.
753
754	// component widgets
755	Scrollbar* d_vertScrollbar; //!< Points to the vertical scroll bar widget.
756	Scrollbar* d_horzScrollbar; //!< Points to the horizontal scroll bar widget.
757	bool d_forceVertScroll; //!< true if vertical scrollbar should always be displayed
758	bool d_forceHorzScroll; //!< true if horizontal scrollbar should always be displayed
759
760	// images
761	const Image* d_selectionBrush; //!< Image to use as the selection brush (should be set by derived class).
762
763	// basic rendering colours
764	colour d_normalTextColour; //!< Text colour used normally.
765	colour d_selectTextColour; //!< Text colour used when text is highlighted
766	colour d_selectBrushColour; //!< Colour to apply to the selection brush.
767	colour d_inactiveSelectBrushColour; //!< Colour to apply to the selection brush when widget is inactive / read-only.
768
769
770	private:
771	/*************************************************************************
772	Static Properties for this class
773	*************************************************************************/
774	static MultiLineEditboxProperties::ReadOnly d_readOnlyProperty;
775	static MultiLineEditboxProperties::WordWrap d_wordWrapProperty;
776	static MultiLineEditboxProperties::CaratIndex d_caratIndexProperty;
777	static MultiLineEditboxProperties::SelectionStart d_selectionStartProperty;
778	static MultiLineEditboxProperties::SelectionLength d_selectionLengthProperty;
779	static MultiLineEditboxProperties::MaxTextLength d_maxTextLengthProperty;
780	static MultiLineEditboxProperties::NormalTextColour d_normalTextColourProperty;
781	static MultiLineEditboxProperties::SelectedTextColour d_selectedTextColourProperty;
782	static MultiLineEditboxProperties::ActiveSelectionColour d_activeSelectionColourProperty;
783	static MultiLineEditboxProperties::InactiveSelectionColour d_inactiveSelectionColourProperty;
784
785
786	/*************************************************************************
787	Private methods
788	*************************************************************************/
789	void addMultiLineEditboxProperties(void);
790	};
791
792	} // End of CEGUI namespace section
793
794	#if defined(_MSC_VER)
795	# pragma warning(pop)
796	#endif
797
798	#endif // end of guard _CEGUIMultiLineEditbox_h_

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

Download in other formats: