source: OGRE/trunk/ogre_dependencies/Dependencies/include/CEGUI/elements/CEGUIMultiLineEditbox.h @ 692

Revision 692, 21.7 KB checked in by mattausch, 19 years ago (diff)

adding ogre 1.2 and dependencies

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
44namespace CEGUI
45{
46/*!
47\brief
48        Base class for the multi-line edit box widget.
49*/
50class CEGUIEXPORT MultiLineEditbox : public Window
51{
52public:
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
373protected:
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        \param name
393           String holding the name to be assigned to the component.
394
395        \return
396                Pointer to a Scrollbar to be used for scrolling vertically.
397        */
398        virtual Scrollbar*      createVertScrollbar(const String& name) const           = 0;
399 
400
401        /*!
402        \brief
403                create and return a pointer to a Scrollbar widget for use as horizontal scroll bar
404
405        \param name
406           String holding the name to be assigned to the component.
407
408        \return
409                Pointer to a Scrollbar to be used for scrolling horizontally.
410        */
411        virtual Scrollbar*      createHorzScrollbar(const String& name) const           = 0;
412
413
414        /*!
415        \brief
416                Perform rendering of the widget control frame and other 'static' areas.  This
417                method should not render the actual text.  Note that the text will be rendered
418                to layer 4 and the selection brush to layer 3, other layers can be used for
419                rendering imagery behind and infront of the text & selection..
420
421        \return
422                Nothing.
423        */
424        virtual void    cacheEditboxBaseImagery()               = 0;
425
426
427        /*!
428        \brief
429                Render the carat.
430
431        \return
432                Nothing
433        */
434        virtual void    cacheCaratImagery(const Rect& textArea) = 0;
435
436
437        /*************************************************************************
438                Implementation Methods
439        *************************************************************************/
440        /*!
441        \brief
442                Add multi-line edit box specific events
443        */
444        void    addMultiLineEditboxEvents(void);
445
446
447        /*!
448        \brief
449                Render text lines.
450        */
451        void    cacheTextLines(const Rect& dest_area);
452
453
454        /*!
455        \brief
456                Format the text into lines as needed by the current formatting options.
457        */
458        void    formatText(void);
459
460
461        /*!
462        \brief
463                Return the length of the next token in String \a text starting at index \a start_idx.
464
465        \note
466                Any single whitespace character is one token, any group of other characters is a token.
467       
468        \return
469                The code point length of the token.
470        */
471        size_t  getNextTokenLength(const String& text, size_t start_idx) const;
472
473
474        virtual void populateRenderCache();
475
476
477        /*!
478        \brief
479                display required integrated scroll bars according to current state of the edit box and update their values.
480        */
481        void    configureScrollbars(void);
482
483
484        /*!
485        \brief
486                Return the text code point index that is rendered closest to screen position \a pt.
487
488        \param pt
489                Point object describing a position on the screen in pixels.
490
491        \return
492                Code point index into the text that is rendered closest to screen position \a pt.
493        */
494        size_t  getTextIndexFromPosition(const Point& pt) const;
495
496
497        /*!
498        \brief
499                Return the line number a given index falls on with the current formatting.  Will return last line
500                if index is out of range.
501        */
502        size_t  getLineNumberFromIndex(size_t index) const;
503
504
505        /*!
506        \brief
507                Clear the current selection setting
508        */
509        void    clearSelection(void);
510
511
512        /*!
513        \brief
514                Erase the currently selected text.
515
516        \param modify_text
517                when true, the actual text will be modified.  When false, everything is done except erasing the characters.
518        */
519        void    eraseSelectedText(bool modify_text = true);
520
521
522        /*!
523        \brief
524                Processing for backspace key
525        */
526        void    handleBackspace(void);
527
528
529        /*!
530        \brief
531                Processing for Delete key
532        */
533        void    handleDelete(void);
534
535
536        /*!
537        \brief
538                Processing to move carat one character left
539        */
540        void    handleCharLeft(uint sysKeys);
541
542
543        /*!
544        \brief
545                Processing to move carat one word left
546        */
547        void    handleWordLeft(uint sysKeys);
548
549
550        /*!
551        \brief
552                Processing to move carat one character right
553        */
554        void    handleCharRight(uint sysKeys);
555
556
557        /*!
558        \brief
559                Processing to move carat one word right
560        */
561        void    handleWordRight(uint sysKeys);
562
563
564        /*!
565        \brief
566                Processing to move carat to the start of the text.
567        */
568        void    handleDocHome(uint sysKeys);
569
570
571        /*!
572        \brief
573                Processing to move carat to the end of the text
574        */
575        void    handleDocEnd(uint sysKeys);
576
577
578        /*!
579        \brief
580                Processing to move carat to the start of the current line.
581        */
582        void    handleLineHome(uint sysKeys);
583
584
585        /*!
586        \brief
587                Processing to move carat to the end of the current line
588        */
589        void    handleLineEnd(uint sysKeys);
590
591
592        /*!
593        \brief
594                Processing to move carat up a line.
595        */
596        void    handleLineUp(uint sysKeys);
597
598
599        /*!
600        \brief
601                Processing to move carat down a line.
602        */
603        void    handleLineDown(uint sysKeys);
604
605
606        /*!
607        \brief
608                Processing to insert a new line / paragraph.
609        */
610        void    handleNewLine(uint sysKeys);
611
612
613        /*!
614        \brief
615                Return whether this window was inherited from the given class name at some point in the inheritance heirarchy.
616
617        \param class_name
618                The class name that is to be checked.
619
620        \return
621                true if this window was inherited from \a class_name. false if not.
622        */
623        virtual bool    testClassName_impl(const String& class_name) const
624        {
625                if ((class_name==(const utf8*)"MultiLineEditBox") ||
626                        (class_name==(const utf8*)"MultiLineEditbox"))
627                {
628                        return true;
629                }
630
631                return Window::testClassName_impl(class_name);
632        }
633
634        /*!
635        \brief
636           Internal handler that is triggered when the user interacts with the scrollbars.
637    */
638    bool handle_scrollChange(const EventArgs& args);
639
640
641        /*************************************************************************
642                New event handlers
643        *************************************************************************/
644        /*!
645        \brief
646                Handler called when the read-only state of the edit box changes
647        */
648        void    onReadOnlyChanged(WindowEventArgs& e);
649
650
651        /*!
652        \brief
653                Handler called when the word wrap mode for the the edit box changes
654        */
655        void    onWordWrapModeChanged(WindowEventArgs& e);
656
657
658        /*!
659        \brief
660                Handler called when the maximum text length for the edit box changes
661        */
662        void    onMaximumTextLengthChanged(WindowEventArgs& e);
663
664
665        /*!
666        \brief
667                Handler called when the carat moves.
668        */
669        void    onCaratMoved(WindowEventArgs& e);
670
671
672        /*!
673        \brief
674                Handler called when the text selection changes
675        */
676        void    onTextSelectionChanged(WindowEventArgs& e);
677
678
679        /*!
680        \brief
681                Handler called when the edit box is full
682        */
683        void    onEditboxFullEvent(WindowEventArgs& e);
684
685
686        /*!
687        \brief
688                Handler called when the 'always show' setting for the vertical scroll bar changes.
689        */
690        void    onVertScrollbarModeChanged(WindowEventArgs& e);
691
692
693        /*!
694        \brief
695                Handler called when 'always show' setting for the horizontal scroll bar changes.
696        */
697        void    onHorzScrollbarModeChanged(WindowEventArgs& e);
698
699
700        /*************************************************************************
701                Overridden event handlers
702        *************************************************************************/
703        virtual void    onMouseButtonDown(MouseEventArgs& e);
704        virtual void    onMouseButtonUp(MouseEventArgs& e);
705        virtual void    onMouseDoubleClicked(MouseEventArgs& e);
706        virtual void    onMouseTripleClicked(MouseEventArgs& e);
707        virtual void    onMouseMove(MouseEventArgs& e);
708        virtual void    onCaptureLost(WindowEventArgs& e);
709        virtual void    onCharacter(KeyEventArgs& e);
710        virtual void    onKeyDown(KeyEventArgs& e);
711        virtual void    onTextChanged(WindowEventArgs& e);
712        virtual void    onSized(WindowEventArgs& e);
713        virtual void    onMouseWheel(MouseEventArgs& e);
714
715
716        /*************************************************************************
717                Implementation struct
718        *************************************************************************/
719        /*!
720        \brief
721                struct used to store information about a formatted line within the
722                paragraph.
723        */
724        struct LineInfo
725        {
726                size_t  d_startIdx;             //!< Starting index for this line.
727                size_t  d_length;               //!< Code point length of this line.
728                float   d_extent;               //!< Rendered extent of this line.
729        };
730
731
732        /*************************************************************************
733                Implementation data
734        *************************************************************************/
735        bool    d_readOnly;                     //!< true if the edit box is in read-only mode
736        size_t  d_maxTextLen;           //!< Maximum number of characters for this Editbox.
737        size_t  d_caratPos;                     //!< Position of the carat / insert-point.
738        size_t  d_selectionStart;       //!< Start of selection area.
739        size_t  d_selectionEnd;         //!< End of selection area.
740        bool    d_dragging;                     //!< true when a selection is being dragged.
741        size_t  d_dragAnchorIdx;        //!< Selection index for drag selection anchor point.
742
743        typedef std::vector<LineInfo>   LineList;       //!< Type for collection of LineInfos.
744        static String d_lineBreakChars; //!< Holds what we consider to be line break characters.
745        bool            d_wordWrap;                     //!< true when formatting uses word-wrapping.
746        LineList        d_lines;                        //!< Holds the lines for the current formatting.
747        float           d_widestExtent;         //!< Holds the extent of the widest line as calculated in the last formatting pass.
748
749        // component widgets
750        Scrollbar*      d_vertScrollbar;        //!< Points to the vertical scroll bar widget.
751        Scrollbar*      d_horzScrollbar;        //!< Points to the horizontal scroll bar widget.
752        bool    d_forceVertScroll;              //!< true if vertical scrollbar should always be displayed
753        bool    d_forceHorzScroll;              //!< true if horizontal scrollbar should always be displayed
754
755        // images
756        const Image*    d_selectionBrush;       //!< Image to use as the selection brush (should be set by derived class).
757
758        // basic rendering colours
759        colour  d_normalTextColour;                             //!< Text colour used normally.
760        colour  d_selectTextColour;                             //!< Text colour used when text is highlighted
761        colour  d_selectBrushColour;                    //!< Colour to apply to the selection brush.
762        colour  d_inactiveSelectBrushColour;    //!< Colour to apply to the selection brush when widget is inactive / read-only.
763
764
765private:
766        /*************************************************************************
767                Static Properties for this class
768        *************************************************************************/
769        static MultiLineEditboxProperties::ReadOnly                                     d_readOnlyProperty;
770        static MultiLineEditboxProperties::WordWrap                                     d_wordWrapProperty;
771        static MultiLineEditboxProperties::CaratIndex                           d_caratIndexProperty;
772        static MultiLineEditboxProperties::SelectionStart                       d_selectionStartProperty;
773        static MultiLineEditboxProperties::SelectionLength                      d_selectionLengthProperty;
774        static MultiLineEditboxProperties::MaxTextLength                        d_maxTextLengthProperty;
775        static MultiLineEditboxProperties::NormalTextColour                     d_normalTextColourProperty;
776        static MultiLineEditboxProperties::SelectedTextColour           d_selectedTextColourProperty;
777        static MultiLineEditboxProperties::ActiveSelectionColour        d_activeSelectionColourProperty;
778        static MultiLineEditboxProperties::InactiveSelectionColour      d_inactiveSelectionColourProperty;
779
780
781        /*************************************************************************
782                Private methods
783        *************************************************************************/
784        void    addMultiLineEditboxProperties(void);
785};
786
787} // End of  CEGUI namespace section
788
789#if defined(_MSC_VER)
790#       pragma warning(pop)
791#endif
792
793#endif  // end of guard _CEGUIMultiLineEditbox_h_
Note: See TracBrowser for help on using the repository browser.