1 /***********************************************************************
2     created:    8/6/2004
3     author:     Paul D Turner
4 
5     purpose:    Interface to base class for list items
6 *************************************************************************/
7 /***************************************************************************
8  *   Copyright (C) 2004 - 2006 Paul D Turner & The CEGUI Development Team
9  *
10  *   Permission is hereby granted, free of charge, to any person obtaining
11  *   a copy of this software and associated documentation files (the
12  *   "Software"), to deal in the Software without restriction, including
13  *   without limitation the rights to use, copy, modify, merge, publish,
14  *   distribute, sublicense, and/or sell copies of the Software, and to
15  *   permit persons to whom the Software is furnished to do so, subject to
16  *   the following conditions:
17  *
18  *   The above copyright notice and this permission notice shall be
19  *   included in all copies or substantial portions of the Software.
20  *
21  *   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
22  *   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
23  *   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
24  *   IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
25  *   OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
26  *   ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
27  *   OTHER DEALINGS IN THE SOFTWARE.
28  ***************************************************************************/
29 #ifndef _CEGUIListboxItem_h_
30 #define _CEGUIListboxItem_h_
31 
32 #include "../Base.h"
33 #include "../String.h"
34 #include "../ColourRect.h"
35 #include "../TextUtils.h"
36 #include "../Size.h"
37 #include "../Rect.h"
38 
39 #if defined(_MSC_VER)
40 #  pragma warning(push)
41 #  pragma warning(disable : 4251)
42 #endif
43 
44 // Start of CEGUI namespace section
45 namespace CEGUI
46 {
47 /*!
48 \brief
49     Base class for list box items
50 */
51 class CEGUIEXPORT ListboxItem :
52     public AllocatedObject<ListboxItem>
53 {
54 public:
55     /*************************************************************************
56         Constants
57     *************************************************************************/
58     static const Colour DefaultSelectionColour;     //!< Default selection brush colour.
59 
60 
61     /*************************************************************************
62         Construction and Destruction
63     *************************************************************************/
64     /*!
65     \brief
66         base class constructor
67     */
68     ListboxItem(const String& text, uint item_id = 0, void* item_data = 0, bool disabled = false, bool auto_delete = true);
69 
70 
71     /*!
72     \brief
73         base class destructor
74     */
75     virtual ~ListboxItem(void);
76 
77 
78     /*************************************************************************
79         Accessors
80     *************************************************************************/
81     /*!
82     \brief
83         return the text string set for this list box item.
84 
85         Note that even if the item does not render text, the text string can still be useful, since it
86         is used for sorting list box items.
87 
88     \return
89         String object containing the current text for the list box item.
90     */
getTooltipText(void)91     const String&   getTooltipText(void) const      {return d_tooltipText;}
92 
getText(void)93     const String& getText(void) const {return d_textLogical;}
94 
95     //! return text string with \e visual ordering of glyphs.
96     const String& getTextVisual() const;
97 
98     /*!
99     \brief
100         Return the current ID assigned to this list box item.
101 
102         Note that the system does not make use of this value, client code can assign any meaning it
103         wishes to the ID.
104 
105     \return
106         ID code currently assigned to this list box item
107     */
getID(void)108     uint    getID(void) const           {return d_itemID;}
109 
110 
111     /*!
112     \brief
113         Return the pointer to any client assigned user data attached to this lis box item.
114 
115         Note that the system does not make use of this data, client code can assign any meaning it
116         wishes to the attached data.
117 
118     \return
119         Pointer to the currently assigned user data.
120     */
getUserData(void)121     void*   getUserData(void) const     {return d_itemData;}
122 
123 
124     /*!
125     \brief
126         return whether this item is selected.
127 
128     \return
129         true if the item is selected, false if the item is not selected.
130     */
isSelected(void)131     bool    isSelected(void) const      {return d_selected;}
132 
133 
134     /*!
135     \brief
136         return whether this item is disabled.
137 
138     \return
139         true if the item is disabled, false if the item is enabled.
140     */
isDisabled(void)141     bool    isDisabled(void) const      {return d_disabled;}
142 
143 
144     /*!
145     \brief
146         return whether this item will be automatically deleted when the list box it is attached to
147         is destroyed, or when the item is removed from the list box.
148 
149     \return
150         true if the item object will be deleted by the system when the list box it is attached to is
151         destroyed, or when the item is removed from the list.  false if client code must destroy the
152         item after it is removed from the list.
153     */
isAutoDeleted(void)154     bool    isAutoDeleted(void) const   {return d_autoDelete;}
155 
156 
157     /*!
158     \brief
159         Get the owner window for this ListboxItem.
160 
161         The owner of a ListboxItem is typically set by the list box widgets when an item is added or inserted.
162 
163     \return
164         Ponter to the window that is considered the owner of this ListboxItem.
165     */
getOwnerWindow()166     const Window*   getOwnerWindow() const      {return d_owner;}
167 
168 
169     /*!
170     \brief
171         Return the current colours used for selection highlighting.
172 
173     \return
174         ColourRect object describing the currently set colours
175     */
getSelectionColours(void)176     ColourRect  getSelectionColours(void) const     {return d_selectCols;}
177 
178 
179     /*!
180     \brief
181         Return the current selection highlighting brush.
182 
183     \return
184         Pointer to the Image object currently used for selection highlighting.
185     */
getSelectionBrushImage(void)186     const Image*    getSelectionBrushImage(void) const      {return d_selectBrush;}
187 
188 
189     /*************************************************************************
190         Manipulators
191     *************************************************************************/
192     /*!
193     \brief
194         set the text string for this list box item.
195 
196         Note that even if the item does not render text, the text string can still be useful, since it
197         is used for sorting list box items.
198 
199     \param text
200         String object containing the text to set for the list box item.
201 
202     \return
203         Nothing.
204     */
205     virtual void setText(const String& text);
206 
setTooltipText(const String & text)207     void    setTooltipText(const String& text)      {d_tooltipText = text;}
208 
209     /*!
210     \brief
211         Set the ID assigned to this list box item.
212 
213         Note that the system does not make use of this value, client code can assign any meaning it
214         wishes to the ID.
215 
216     \param item_id
217         ID code to be assigned to this list box item
218 
219     \return
220         Nothing.
221     */
setID(uint item_id)222     void    setID(uint item_id)     {d_itemID = item_id;}
223 
224 
225     /*!
226     \brief
227         Set the client assigned user data attached to this lis box item.
228 
229         Note that the system does not make use of this data, client code can assign any meaning it
230         wishes to the attached data.
231 
232     \param item_data
233         Pointer to the user data to attach to this list item.
234 
235     \return
236         Nothing.
237     */
setUserData(void * item_data)238     void    setUserData(void* item_data)    {d_itemData = item_data;}
239 
240 
241     /*!
242     \brief
243         set whether this item is selected.
244 
245     \param setting
246         true if the item is selected, false if the item is not selected.
247 
248     \return
249         Nothing.
250     */
setSelected(bool setting)251     void    setSelected(bool setting)       {d_selected = setting;}
252 
253 
254     /*!
255     \brief
256         set whether this item is disabled.
257 
258     \param setting
259         true if the item is disabled, false if the item is enabled.
260 
261     \return
262         Nothing.
263     */
setDisabled(bool setting)264     void    setDisabled(bool setting)       {d_disabled = setting;}
265 
266     /*!
267     \brief
268         Set whether this item will be automatically deleted when the list box it is attached to
269         is destroyed, or when the item is removed from the list box.
270 
271     \param setting
272         true if the item object should be deleted by the system when the list box it is attached to is
273         destroyed, or when the item is removed from the list.  false if client code will destroy the
274         item after it is removed from the list.
275 
276     \return
277         Nothing.
278     */
setAutoDeleted(bool setting)279     void    setAutoDeleted(bool setting)        {d_autoDelete = setting;}
280 
281 
282     /*!
283     \brief
284         Set the owner window for this ListboxItem.  This is called by all the list box widgets when
285         an item is added or inserted.
286 
287     \param owner
288         Ponter to the window that should be considered the owner of this ListboxItem.
289 
290     \return
291         Nothing
292     */
setOwnerWindow(const Window * owner)293     void    setOwnerWindow(const Window* owner)     {d_owner = owner;}
294 
295 
296     /*!
297     \brief
298         Set the colours used for selection highlighting.
299 
300     \param cols
301         ColourRect object describing the colours to be used.
302 
303     \return
304         Nothing.
305     */
setSelectionColours(const ColourRect & cols)306     void    setSelectionColours(const ColourRect& cols)     {d_selectCols = cols;}
307 
308 
309     /*!
310     \brief
311         Set the colours used for selection highlighting.
312 
313     \param top_left_colour
314         Colour (as ARGB value) to be applied to the top-left corner of the selection area.
315 
316     \param top_right_colour
317         Colour (as ARGB value) to be applied to the top-right corner of the selection area.
318 
319     \param bottom_left_colour
320         Colour (as ARGB value) to be applied to the bottom-left corner of the selection area.
321 
322     \param bottom_right_colour
323         Colour (as ARGB value) to be applied to the bottom-right corner of the selection area.
324 
325     \return
326         Nothing.
327     */
328     void    setSelectionColours(Colour top_left_colour, Colour top_right_colour, Colour bottom_left_colour, Colour bottom_right_colour);
329 
330 
331     /*!
332     \brief
333         Set the colours used for selection highlighting.
334 
335     \param col
336         colour value to be used when rendering.
337 
338     \return
339         Nothing.
340     */
setSelectionColours(Colour col)341     void    setSelectionColours(Colour col)     {setSelectionColours(col, col, col, col);}
342 
343 
344     /*!
345     \brief
346         Set the selection highlighting brush image.
347 
348     \param image
349         Pointer to the Image object to be used for selection highlighting.
350 
351     \return
352         Nothing.
353     */
setSelectionBrushImage(const Image * image)354     void    setSelectionBrushImage(const Image* image)      {d_selectBrush = image;}
355 
356 
357     /*!
358     \brief
359         Set the selection highlighting brush image.
360 
361     \param name
362         Name of the image to be used
363 
364     \return
365         Nothing.
366     */
367     void    setSelectionBrushImage(const String& name);
368 
369     /*!
370     \brief
371         Perform any updates needed because the given font's render size has
372         changed.
373 
374     /note
375         The base implementation just returns false.
376 
377     \param font
378         Pointer to the Font whose render size has changed.
379 
380     \return
381         - true if some action was taken.
382         - false if no action was taken (i.e font is not used here).
383     */
384     virtual bool handleFontRenderSizeChange(const Font* const font);
385 
386     /*************************************************************************
387         Abstract portion of interface
388     *************************************************************************/
389     /*!
390     \brief
391         Return the rendered pixel size of this list box item.
392 
393     \return
394         Size object describing the size of the list box item in pixels.
395     */
396     virtual Sizef getPixelSize(void) const = 0;
397 
398 
399     /*!
400     \brief
401         Draw the list box item in its current state
402 
403     \param position
404         Vecor2 object describing the upper-left corner of area that should be rendered in to for the draw operation.
405 
406     \param alpha
407         Alpha value to be used when rendering the item (between 0.0f and 1.0f).
408 
409     \param clipper
410         Rect object describing the clipping rectangle for the draw operation.
411 
412     \return
413         Nothing.
414     */
415     virtual void draw(GeometryBuffer& buffer, const Rectf& targetRect,
416                       float alpha, const Rectf* clipper) const = 0;
417 
418     /*************************************************************************
419         Operators
420     *************************************************************************/
421     /*!
422     \brief
423         Less-than operator, compares item texts.
424     */
425     virtual bool    operator<(const ListboxItem& rhs) const     {return getText() < rhs.getText();}
426 
427 
428     /*!
429     \brief
430         Greater-than operator, compares item texts.
431     */
432     virtual bool    operator>(const ListboxItem& rhs) const     {return getText() > rhs.getText();}
433 
434 
435 protected:
436     /*************************************************************************
437         Implementation methods
438     *************************************************************************/
439     /*!
440     \brief
441         Return a ColourRect object describing the colours in \a cols after having their alpha
442         component modulated by the value \a alpha.
443     */
444     ColourRect getModulateAlphaColourRect(const ColourRect& cols, float alpha) const;
445 
446 
447     /*!
448     \brief
449         Return a colour value describing the colour specified by \a col after having its alpha
450         component modulated by the value \a alpha.
451     */
452     Colour calculateModulatedAlphaColour(Colour col, float alpha) const;
453 
454 
455     /*************************************************************************
456         Implementation Data
457     *************************************************************************/
458     String d_textLogical;
459     //! pointer to bidirection support object
460     BidiVisualMapping* d_bidiVisualMapping;
461     //! whether bidi visual mapping has been updated since last text change.
462     mutable bool d_bidiDataValid;
463     String  d_tooltipText;  //!< Text for the individual tooltip of this item
464     uint    d_itemID;       //!< ID code assigned by client code.  This has no meaning within the GUI system.
465     void*   d_itemData;     //!< Pointer to some client code data.  This has no meaning within the GUI system.
466     bool    d_selected;     //!< true if this item is selected.  false if the item is not selected.
467     bool    d_disabled;     //!< true if this item is disabled.  false if the item is not disabled.
468     bool    d_autoDelete;   //!< true if the system should destroy this item, false if client code will destroy the item.
469     const Window*   d_owner;    //!< Pointer to the window that owns this item.
470     ColourRect      d_selectCols;       //!< Colours used for selection highlighting.
471     const Image*    d_selectBrush;      //!< Image used for rendering selection.
472 };
473 
474 } // End of  CEGUI namespace section
475 
476 #if defined(_MSC_VER)
477 #  pragma warning(pop)
478 #endif
479 
480 #endif  // end of guard _CEGUIListboxItem_h_
481