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

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

adding ogre 1.2 and dependencies

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
41namespace CEGUI
42{
43// forward declare implementation data type
44struct RegexValidator;
45
46
47/*!
48\brief
49        Base class for an Editbox widget
50*/
51class CEGUIEXPORT Editbox : public Window
52{
53public:
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
442protected:
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
684private:
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.