NXWidgets: clistbox.hxx Source File

NXWidgets 1.19

clistbox.hxx
Go to the documentation of this file.
1 /****************************************************************************
2 * NxWidgets/libnxwidgets/include/clistbox.hxx
3 *
4 * Copyright (C) 2012 Gregory Nutt. All rights reserved.
5 * Author: Gregory Nutt <gnutt@nuttx.org>
6 *
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
9 * are met:
10 *
11 * 1. Redistributions of source code must retain the above copyright
12 * notice, this list of conditions and the following disclaimer.
13 * 2. Redistributions in binary form must reproduce the above copyright
14 * notice, this list of conditions and the following disclaimer in
15 * the documentation and/or other materials provided with the
16 * distribution.
17 * 3. Neither the name NuttX, NxWidgets, nor the names of its contributors
18 * me be used to endorse or promote products derived from this software
19 * without specific prior written permission.
20 *
21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
24 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
25 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
26 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
27 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
28 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
29 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
31 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
32 * POSSIBILITY OF SUCH DAMAGE.
33 *
34 ****************************************************************************
35 *
36 * Portions of this package derive from Woopsi (http://woopsi.org/) and
37 * portions are original efforts. It is difficult to determine at this
38 * point what parts are original efforts and which parts derive from Woopsi.
39 * However, in any event, the work of Antony Dzeryn will be acknowledged
40 * in all NxWidget files. Thanks Antony!
41 *
42 * Copyright (c) 2007-2011, Antony Dzeryn
43 * All rights reserved.
44 *
45 * Redistribution and use in source and binary forms, with or without
46 * modification, are permitted provided that the following conditions are met:
47 *
48 * * Redistributions of source code must retain the above copyright
49 * notice, this list of conditions and the following disclaimer.
50 * * Redistributions in binary form must reproduce the above copyright
51 * notice, this list of conditions and the following disclaimer in the
52 * documentation and/or other materials provided with the distribution.
53 * * Neither the names "Woopsi", "Simian Zombie" nor the
54 * names of its contributors may be used to endorse or promote products
55 * derived from this software without specific prior written permission.
56 *
57 * THIS SOFTWARE IS PROVIDED BY Antony Dzeryn ``AS IS'' AND ANY
58 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
59 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
60 * DISCLAIMED. IN NO EVENT SHALL Antony Dzeryn BE LIABLE FOR ANY
61 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
62 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
63 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
64 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
65 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
66 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
67 *
68 ****************************************************************************/
69
70 #ifndef __INCLUDE_CLISTBOX_HXX
71 #define __INCLUDE_CLISTBOX_HXX
72
73 /****************************************************************************
74 * Included Files
75 ****************************************************************************/
76
77 #include <nuttx/config.h>
78
79 #include <cstdint>
80 #include <cstdbool>
81
82 #include <nuttx/nx/nxglib.h>
83
84 #include "nxconfig.hxx"
85 #include "cscrollingpanel.hxx"
86 #include "ilistdataeventhandler.hxx"
87 #include "clistdata.hxx"
88 #include "clistboxdataitem.hxx"
89 #include "cwidgetstyle.hxx"
90 #include "ilistbox.hxx"
91
92 /****************************************************************************
93 * Pre-Processor Definitions
94 ****************************************************************************/
95
96 /****************************************************************************
97 * Implementation Classes
98 ****************************************************************************/
99
100 #if defined(__cplusplus)
101
102 namespace NXWidgets
103 {
104 /**
105 * Class providing a scrollable list of options. The CListBox can be set
106 * up to only allow one selection or multiple selections. Processes
107 * double-clicks and raises double-click events, so that a double-click
108 * on an option can be made to automatically select and close a window/etc.
109 * The options themselves have user-definable text and background colors
110 * for their selected and unselected states.
111 */
112
113 class CListBox : public IListBox, public CScrollingPanel,
114 public IListDataEventHandler
115 {
116 protected:
117 CListData m_options; /**< Option storage. */
118 uint8_t m_optionPadding; /**< Padding between options. */
119 int m_lastSelectedIndex; /**< Index of the last option selected. */
120
121 /**
122 * Draw the area of this widget that falls within the clipping region.
123 * Called by the redraw() function to draw all visible regions.
124 *
125 * @param port The CGraphicsPort to draw to.
126 * @see redraw()
127 */
128
129 virtual void drawContents(CGraphicsPort *port);
130
131 /**
132 * Draw the area of this widget that falls within the clipping region.
133 * Called by the redraw() function to draw all visible regions.
134 *
135 * @param port The CGraphicsPort to draw to.
136 * @see redraw()
137 */
138
139 virtual void drawBorder(CGraphicsPort *port);
140
141 /**
142 * Determines which item was clicked and selects or deselects it as
143 * appropriate. Also starts the dragging system.
144 *
145 * @param x The x coordinate of the click.
146 * @param y The y coordinate of the click.
147 */
148
149 virtual void onClick(nxgl_coord_t x, nxgl_coord_t y);
150
151 /**
152 * Selects the clicked item and deselects all others.
153 *
154 * @param x The x coordinate of the click.
155 * @param y The y coordinate of the click.
156 */
157
158 virtual void onDoubleClick(nxgl_coord_t x, nxgl_coord_t y);
159
160 /**
161 * Select or deselect an option by its index. Does not deselect any other
162 * selected options. Set index to -1 to select nothing. Redraws the widget
163 * and raises a value changed event.
164 *
165 * @param index The index of the option to select.
166 * @param selected True to select the option, false to deselect it.
167 */
168
169 virtual void setOptionSelected(const int index, const bool selected);
170
171 /**
172 * Copy constructor is protected to prevent usage.
173 */
174
175 inline CListBox(const CListBox &listBox) : CScrollingPanel(listBox) { }
176
177 public:
178
179 /**
180 * Constructor.
181 *
182 * @param pWidgetControl The controlling widget for the display.
183 * @param x The x coordinate of the widget.
184 * @param y The y coordinate of the widget.
185 * @param width The width of the widget.
186 * @param height The height of the widget.
187 * @param style The style that the widget should use. If this is not
188 * specified, the widget will use the values stored in the global
189 * g_defaultWidgetStyle object. The widget will copy the properties of
190 * the style into its own internal style object.
191 */
192
193 CListBox(CWidgetControl *pWidgetControl,
194 nxgl_coord_t x, nxgl_coord_t y,
195 nxgl_coord_t width, nxgl_coord_t height,
196 CWidgetStyle *style = (CWidgetStyle *)NULL);
197
198 /**
199 * Destructor.
200 */
201
202 virtual ~CListBox(void);
203
204 /**
205 * Add a new option to the widget using default colors.
206 *
207 * @param text Text to show in the option.
208 * @param value The value of the option.
209 */
210
211 virtual void addOption(const CNxString &text, const uint32_t value);
212
213 /**
214 * Add an option to the widget.
215 *
216 * @param option The option to add.
217 */
218
219 virtual void addOption(CListBoxDataItem *option);
220
221 /**
222 * Remove an option from the widget by its index.
223 *
224 * @param index The index of the option to remove.
225 */
226
227 virtual void removeOption(const int index);
228
229 /**
230 * Remove all options from the widget.
231 */
232
233 virtual void removeAllOptions(void);
234
235 /**
236 * Add a new option to the widget.
237 *
238 * @param text Text to show in the option.
239 * @param value The value of the option.
240 * @param normalTextColor Color to draw the text with when not selected.
241 * @param normalBackColor Color to draw the background with when not selected.
242 * @param selectedTextColor Color to draw the text with when selected.
243 * @param selectedBackColor Color to draw the background with when selected.
244 */
245
246 virtual void addOption(const CNxString &text, const uint32_t value,
247 const nxwidget_pixel_t normalTextColor,
248 const nxwidget_pixel_t normalBackColor,
249 const nxwidget_pixel_t selectedTextColor,
250 const nxwidget_pixel_t selectedBackColor);
251
252 /**
253 * Select an option by its index.
254 * Redraws the widget and raises a value changed event.
255 *
256 * @param index The index of the option to select.
257 */
258
259 virtual void selectOption(const int index);
260
261 /**
262 * De-select an option by its index.
263 * Redraws the widget and raises a value changed event.
264 *
265 * @param index The index of the option to select.
266 */
267
268 virtual void deselectOption(const int index);
269
270 /**
271 * Select all options. Does nothing if the listbox does not allow
272 * multiple selections. Redraws the widget and raises a value changed
273 * event.
274 */
275
276 virtual void selectAllOptions(void);
277
278 /**
279 * Deselect all options.
280 * Redraws the widget and raises a value changed event.
281 */
282
283 virtual void deselectAllOptions(void);
284
285 /**
286 * Get the selected index. Returns -1 if nothing is selected. If
287 * more than one option is selected, the index of the first selected
288 * option is returned.
289 *
290 * @return The selected index.
291 */
292
293 virtual const int getSelectedIndex(void) const;
294
295 /**
296 * Sets the selected index. Specify -1 to select nothing. Resets any
297 * other selected options to deselected. Redraws the widget and raises
298 * a value changed event.
299 *
300 * @param index The selected index.
301 */
302
303 virtual void setSelectedIndex(const int index);
304
305 /**
306 * Get the selected option. Returns NULL if nothing is selected.
307 *
308 * @return The selected option.
309 */
310
311 virtual const CListBoxDataItem *getSelectedOption(void) const;
312
313 /**
314 * Sets whether multiple selections are possible or not.
315 *
316 * @param allowMultipleSelections True to allow multiple selections.
317 */
318
319 virtual inline void
320 setAllowMultipleSelections(const bool allowMultipleSelections)
321 {
322 m_options.setAllowMultipleSelections(allowMultipleSelections);
323 }
324
325 /**
326 * Sets whether multiple selections are possible or not.
327 *
328 * @return True if multiple selections are allowed.
329 */
330
331 virtual inline const bool allowsMultipleSelections(void) const
332 {
333 return m_options.allowsMultipleSelections();
334 }
335
336 /**
337 * Resize the scrolling canvas to encompass all options.
338 */
339
340 virtual void resizeCanvas(void);
341
342 /**
343 * Get the specified option.
344 *
345 * @return The specified option.
346 */
347
348 virtual inline const CListBoxDataItem *getOption(const int index)
349 {
350 return (const CListBoxDataItem *)m_options.getItem(index);
351 }
352
353 /**
354 * Sort the options alphabetically by the text of the options.
355 */
356
357 virtual void sort(void);
358
359 /**
360 * Get the total number of options.
361 *
362 * @return The number of options.
363 */
364
365 virtual inline const int getOptionCount(void) const
366 {
367 return m_options.getItemCount();
368 }
369
370 /**
371 * Get the height of a single option.
372 *
373 * @return The height of an option.
374 */
375
376 virtual const nxgl_coord_t getOptionHeight(void) const;
377
378 /**
379 * Sets whether or not items added to the list are automatically sorted on insert or not.
380 *
381 * @param sortInsertedItems True to enable sort on insertion.
382 */
383
384 virtual inline void setSortInsertedItems(const bool sortInsertedItems)
385 {
386 m_options.setSortInsertedItems(sortInsertedItems);
387 }
388
389 /**
390 * Handles list data changed events.
391 *
392 * @param e Event arguments.
393 */
394
395 virtual void handleListDataChangedEvent(const CListDataEventArgs &e);
396
397 /**
398 * Handles list selection changed events.
399 *
400 * @param e Event arguments.
401 */
402
403 virtual void handleListDataSelectionChangedEvent(const CListDataEventArgs &e);
404
405 /**
406 * Insert the dimensions that this widget wants to have into the rect
407 * passed in as a parameter. All coordinates are relative to the widget's
408 * parent. Value is based on the length of the largest string in the
409 * set of options.
410 *
411 * @param rect Reference to a rect to populate with data.
412 */
413
414 virtual void getPreferredDimensions(CRect &rect) const;
415
416 /**
417 * Check if the click is a double-click.
418 *
419 * @param x X coordinate of the click.
420 * @param y Y coordinate of the click.
421 * @return True if the click is a double-click.
422 */
423
424 virtual bool isDoubleClick(nxgl_coord_t x, nxgl_coord_t y);
425 };
426 }
427
428 #endif // __cplusplus
429
430 #endif // __INCLUDE_CLISTBOX_HXX
431
NXWidgets::CListBox::getPreferredDimensions
virtual void getPreferredDimensions(CRect &rect) const
Definition: clistbox.cxx:371
NXWidgets::CWidgetStyle
Definition: cwidgetstyle.hxx:125
clistboxdataitem.hxx
NXWidgets::CListData::getItem
virtual const CListDataItem * getItem(const int index) const
Definition: clistdata.hxx:260
NXWidgets::CListBox::removeOption
virtual void removeOption(const int index)
Definition: clistbox.cxx:167
NXWidgets::CListBox::sort
virtual void sort(void)
Definition: clistbox.cxx:319
NXWidgets::CListBox::getOptionCount
virtual const int getOptionCount(void) const
Definition: clistbox.hxx:365
NXWidgets::CListBox::handleListDataSelectionChangedEvent
virtual void handleListDataSelectionChangedEvent(const CListDataEventArgs &e)
Definition: clistbox.cxx:356
NXWidgets::CListBox::m_options
CListData m_options
Definition: clistbox.hxx:117
NXWidgets::CWidgetControl
Definition: cwidgetcontrol.hxx:95
NXWidgets::CListBox::allowsMultipleSelections
virtual const bool allowsMultipleSelections(void) const
Definition: clistbox.hxx:331
NXWidgets::CListBox::resizeCanvas
virtual void resizeCanvas(void)
Definition: clistbox.cxx:289
NXWidgets::CListBox::setSelectedIndex
virtual void setSelectedIndex(const int index)
Definition: clistbox.cxx:269
NXWidgets::CListBox::onClick
virtual void onClick(nxgl_coord_t x, nxgl_coord_t y)
Definition: clistbox.cxx:601
clistdata.hxx
NXWidgets::IListDataEventHandler
Definition: ilistdataeventhandler.hxx:103
NXWidgets::CScrollingPanel
Definition: cscrollingpanel.hxx:105
NXWidgets::CListBox::onDoubleClick
virtual void onDoubleClick(nxgl_coord_t x, nxgl_coord_t y)
Definition: clistbox.cxx:640
NXWidgets::CListBoxDataItem
Definition: clistboxdataitem.hxx:104
NXWidgets::CListBox::deselectAllOptions
virtual void deselectAllOptions(void)
Definition: clistbox.cxx:243
NXWidgets::CListBox::selectAllOptions
virtual void selectAllOptions(void)
Definition: clistbox.cxx:233
cwidgetstyle.hxx
NXWidgets::CListBox::m_optionPadding
uint8_t m_optionPadding
Definition: clistbox.hxx:118
NXWidgets::CListBox::m_lastSelectedIndex
int m_lastSelectedIndex
Definition: clistbox.hxx:119
NXWidgets::CListBox::isDoubleClick
virtual bool isDoubleClick(nxgl_coord_t x, nxgl_coord_t y)
Definition: clistbox.cxx:416
NXWidgets::nxwidget_pixel_t
uint8_t nxwidget_pixel_t
Definition: nxconfig.hxx:442
NXWidgets::IListBox
Definition: ilistbox.hxx:102
NXWidgets::CListDataEventArgs
Definition: clistdataeventargs.hxx:103
NXWidgets
Definition: cbgwindow.hxx:65
NXWidgets::CListBox::~CListBox
virtual ~CListBox(void)
Definition: clistbox.cxx:130
NXWidgets::CListBox::getOptionHeight
virtual const nxgl_coord_t getOptionHeight(void) const
Definition: clistbox.cxx:330
NXWidgets::CListBox::setSortInsertedItems
virtual void setSortInsertedItems(const bool sortInsertedItems)
Definition: clistbox.hxx:384
NXWidgets::CListBox::getSelectedIndex
virtual const int getSelectedIndex(void) const
Definition: clistbox.cxx:256
nxconfig.hxx
NXWidgets::CListData::getItemCount
virtual const int getItemCount(void) const
Definition: clistdata.hxx:284
NXWidgets::CListBox::handleListDataChangedEvent
virtual void handleListDataChangedEvent(const CListDataEventArgs &e)
Definition: clistbox.cxx:341
NXWidgets::CListBox::getSelectedOption
virtual const CListBoxDataItem * getSelectedOption(void) const
Definition: clistbox.cxx:280
NXWidgets::CListBox::drawBorder
virtual void drawBorder(CGraphicsPort *port)
Definition: clistbox.cxx:582
NXWidgets::CListBox::setOptionSelected
virtual void setOptionSelected(const int index, const bool selected)
Definition: clistbox.cxx:662
NXWidgets::CRect
Definition: crect.hxx:101
NXWidgets::CListData::setSortInsertedItems
virtual void setSortInsertedItems(const bool sortInsertedItems)
Definition: clistdata.hxx:330
NXWidgets::CListData::setAllowMultipleSelections
virtual void setAllowMultipleSelections(const bool allowMultipleSelections)
Definition: clistdata.hxx:249
NXWidgets::CListBox::deselectOption
virtual void deselectOption(const int index)
Definition: clistbox.cxx:222
NXWidgets::CListBox::drawContents
virtual void drawContents(CGraphicsPort *port)
Definition: clistbox.cxx:446
NXWidgets::CListBox
Definition: clistbox.hxx:113
NXWidgets::CNxString
Definition: cnxstring.hxx:121
NXWidgets::CListData::allowsMultipleSelections
virtual const bool allowsMultipleSelections(void) const
Definition: clistdata.hxx:318
NXWidgets::CListBox::CListBox
CListBox(const CListBox &listBox)
Definition: clistbox.hxx:175
NXWidgets::CListBox::addOption
virtual void addOption(const CNxString &text, const uint32_t value)
Definition: clistbox.cxx:143
NXWidgets::CListBox::setAllowMultipleSelections
virtual void setAllowMultipleSelections(const bool allowMultipleSelections)
Definition: clistbox.hxx:320
NXWidgets::CListBox::removeAllOptions
virtual void removeAllOptions(void)
Definition: clistbox.cxx:176
ilistbox.hxx
cscrollingpanel.hxx
NXWidgets::CListData
Definition: clistdata.hxx:107
NXWidgets::CListBox::getOption
virtual const CListBoxDataItem * getOption(const int index)
Definition: clistbox.hxx:348
ilistdataeventhandler.hxx
NXWidgets::CListBox::selectOption
virtual void selectOption(const int index)
Definition: clistbox.cxx:210
NXWidgets::CGraphicsPort
Definition: cgraphicsport.hxx:106