Context Navigation

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

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

Line
1	/************************************************************************
2	filename: CEGUIScrollbar.h
3	created: 13/4/2004
4	author: Paul D Turner
5
6	purpose: Interface to base class for Scrollbar 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 _CEGUIScrollbar_h_
27	#define _CEGUIScrollbar_h_
28
29	#include "CEGUIBase.h"
30	#include "CEGUIWindow.h"
31	#include "elements/CEGUIScrollbarProperties.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
41	namespace CEGUI
42	{
43	/*!
44	\brief
45	Base scroll bar class.
46
47	This base class for scroll bars does not have any idea of direction - a derived class would
48	add whatever meaning is appropriate according to what that derived class
49	represents to the user.
50	*/
51	class CEGUIEXPORT Scrollbar : public Window
52	{
53	public:
54	static const String EventNamespace; //!< Namespace for global events
55
56	/*************************************************************************
57	Event name constants
58	*************************************************************************/
59	static const String EventScrollPositionChanged; //!< Name of the event fired when the scroll bar position value changes
60	static const String EventThumbTrackStarted; //!< Name of the event fired when the user begins dragging the thumb.
61	static const String EventThumbTrackEnded; //!< Name of the event fired when the user releases the thumb.
62	static const String EventScrollConfigChanged; //!< Name of the event fired when the scroll bar configuration data changes.
63
64
65	/*************************************************************************
66	Accessor functions
67	*************************************************************************/
68	/*!
69	\brief
70	Return the size of the document or data.
71
72	The document size should be thought of as the total size of the data that
73	is being scrolled through (the number of lines in a text file for example).
74
75	\note
76	The returned value has no meaning within the Gui system, it is left up to the
77	application to assign appropriate values for the application specific use of
78	the scroll bar.
79
80	\return
81	float value specifying the currently set document size.
82	*/
83	float getDocumentSize(void) const {return d_documentSize;}
84
85
86	/*!
87	\brief
88	Return the page size for this scroll bar.
89
90	The page size is typically the amount of data that can be displayed at one
91	time. This value is also used when calculating the amount the position will
92	change when you click either side of the scroll bar thumb - the amount the
93	position changes will is (pageSize - overlapSize).
94
95	\note
96	The returned value has no meaning within the Gui system, it is left up to the
97	application to assign appropriate values for the application specific use of
98	the scroll bar.
99
100	\return
101	float value specifying the currently set page size.
102	*/
103	float getPageSize(void) const {return d_pageSize;}
104
105
106	/*!
107	\brief
108	Return the step size for this scroll bar.
109
110	The step size is typically a single unit of data that can be displayed, this is the
111	amount the position will change when you click either of the arrow buttons on the
112	scroll bar. (this could be 1 for a single line of text, for example).
113
114	\note
115	The returned value has no meaning within the Gui system, it is left up to the
116	application to assign appropriate values for the application specific use of
117	the scroll bar.
118
119	\return
120	float value specifying the currently set step size.
121	*/
122	float getStepSize(void) const {return d_stepSize;}
123
124
125	/*!
126	\brief
127	Return the overlap size for this scroll bar.
128
129	The overlap size is the amount of data from the end of a 'page' that will
130	remain visible when the position is moved by a page. This is usually used
131	so that the user keeps some context of where they were within the document's
132	data when jumping a page at a time.
133
134	\note
135	The returned value has no meaning within the Gui system, it is left up to the
136	application to assign appropriate values for the application specific use of
137	the scroll bar.
138
139	\return
140	float value specifying the currently set overlap size.
141	*/
142	float getOverlapSize(void) const {return d_overlapSize;}
143
144
145	/*!
146	\brief
147	Return the current position of scroll bar within the document.
148
149	The range of the scroll bar is from 0 to the size of the document minus the
150	size of a page (0 <= position <= (documentSize - pageSize)).
151
152	\note
153	The returned value has no meaning within the Gui system, it is left up to the
154	application to assign appropriate values for the application specific use of
155	the scroll bar.
156
157	\return
158	float value specifying the current position of the scroll bar within its
159	document.
160	*/
161	float getScrollPosition(void) const {return d_position;}
162
163
164	/*************************************************************************
165	Manipulator Commands
166	*************************************************************************/
167	/*!
168	\brief
169	Initialises the Scrollbar object ready for use.
170
171	\note
172	This must be called for every window created. Normally this is handled automatically by the WindowFactory for each Window type.
173
174	\return
175	Nothing
176	*/
177	virtual void initialise(void);
178
179
180	/*!
181	\brief
182	Set the size of the document or data.
183
184	The document size should be thought of as the total size of the data that
185	is being scrolled through (the number of lines in a text file for example).
186
187	\note
188	The value set has no meaning within the Gui system, it is left up to the
189	application to assign appropriate values for the application specific use of
190	the scroll bar.
191
192	\param document_size
193	float value specifying the document size.
194
195	\return
196	Nothing.
197	*/
198	void setDocumentSize(float document_size);
199
200
201	/*!
202	\brief
203	Set the page size for this scroll bar.
204
205	The page size is typically the amount of data that can be displayed at one
206	time. This value is also used when calculating the amount the position will
207	change when you click either side of the scroll bar thumb - the amount the
208	position changes will is (pageSize - overlapSize).
209
210	\note
211	The value set has no meaning within the Gui system, it is left up to the
212	application to assign appropriate values for the application specific use of
213	the scroll bar.
214
215	\param page_size
216	float value specifying the page size.
217
218	\return
219	Nothing.
220	*/
221	void setPageSize(float page_size);
222
223
224	/*!
225	\brief
226	Set the step size for this scroll bar.
227
228	The step size is typically a single unit of data that can be displayed, this is the
229	amount the position will change when you click either of the arrow buttons on the
230	scroll bar. (this could be 1 for a single line of text, for example).
231
232	\note
233	The value set has no meaning within the Gui system, it is left up to the
234	application to assign appropriate values for the application specific use of
235	the scroll bar.
236
237	\param step_size
238	float value specifying the step size.
239
240	\return
241	Nothing.
242	*/
243	void setStepSize(float step_size);
244
245
246	/*!
247	\brief
248	Set the overlap size for this scroll bar.
249
250	The overlap size is the amount of data from the end of a 'page' that will
251	remain visible when the position is moved by a page. This is usually used
252	so that the user keeps some context of where they were within the document's
253	data when jumping a page at a time.
254
255	\note
256	The value set has no meaning within the Gui system, it is left up to the
257	application to assign appropriate values for the application specific use of
258	the scroll bar.
259
260	\param overlap_size
261	float value specifying the overlap size.
262
263	\return
264	Nothing.
265	*/
266	void setOverlapSize(float overlap_size);
267
268
269	/*!
270	\brief
271	Set the current position of scroll bar within the document.
272
273	The range of the scroll bar is from 0 to the size of the document minus the
274	size of a page (0 <= position <= (documentSize - pageSize)), any attempt to
275	set the position outside this range will be adjusted so that it falls within
276	the legal range.
277
278	\note
279	The returned value has no meaning within the Gui system, it is left up to the
280	application to assign appropriate values for the application specific use of
281	the scroll bar.
282
283	\param position
284	float value specifying the position of the scroll bar within its
285	document.
286
287	\return
288	Nothing.
289	*/
290	void setScrollPosition(float position);
291
292
293	/*************************************************************************
294	Construction / Destruction
295	*************************************************************************/
296	/*!
297	\brief
298	Constructor for Scrollbar objects
299	*/
300	Scrollbar(const String& type, const String& name);
301
302
303	/*!
304	\brief
305	Destructor for Scrollbar objects
306	*/
307	virtual ~Scrollbar(void);
308
309
310	protected:
311	/*************************************************************************
312	Implementation Methods
313	*************************************************************************/
314	/*!
315	\brief
316	Add scroll bar specific events
317	*/
318	void addScrollbarEvents(void);
319
320
321	/*!
322	\brief
323	create a PushButton based widget to use as the increase button for this scroll bar.
324	*/
325	virtual PushButton* createIncreaseButton(void) const = 0;
326
327
328	/*!
329	\brief
330	create a PushButton based widget to use as the decrease button for this scroll bar.
331	*/
332	virtual PushButton* createDecreaseButton(void) const = 0;
333
334
335	/*!
336	\brief
337	create a Thumb based widget to use as the thumb for this scroll bar.
338	*/
339	virtual Thumb* createThumb(void) const = 0;
340
341
342	/*!
343	\brief
344	layout the scroll bar component widgets
345	*/
346	virtual void layoutComponentWidgets(void) = 0;
347
348
349	/*!
350	\brief
351	update the size and location of the thumb to properly represent the current state of the scroll bar
352	*/
353	virtual void updateThumb(void) = 0;
354
355
356	/*!
357	\brief
358	return value that best represents current scroll bar position given the current location of the thumb.
359
360	\return
361	float value that, given the thumb widget position, best represents the current position for the scroll bar.
362	*/
363	virtual float getValueFromThumb(void) const = 0;
364
365
366	/*!
367	\brief
368	Given window location \a pt, return a value indicating what change should be
369	made to the scroll bar.
370
371	\param pt
372	Point object describing a pixel position in window space.
373
374	\return
375	- -1 to indicate scroll bar position should be moved to a lower value.
376	- 0 to indicate scroll bar position should not be changed.
377	- +1 to indicate scroll bar position should be moved to a higher value.
378	*/
379	virtual float getAdjustDirectionFromPoint(const Point& pt) const = 0;
380
381
382	/*!
383	\brief
384	handler function for when thumb moves.
385	*/
386	bool handleThumbMoved(const EventArgs& e);
387
388
389	/*!
390	\brief
391	handler function for when the increase button is clicked.
392	*/
393	bool handleIncreaseClicked(const EventArgs& e);
394
395
396	/*!
397	\brief
398	handler function for when the decrease button is clicked.
399	*/
400	bool handleDecreaseClicked(const EventArgs& e);
401
402
403	/*!
404	\brief
405	handler function for when thumb tracking begins
406	*/
407	bool handleThumbTrackStarted(const EventArgs& e);
408
409
410	/*!
411	\brief
412	handler function for when thumb tracking begins
413	*/
414	bool handleThumbTrackEnded(const EventArgs& e);
415
416
417	/*!
418	\brief
419	Return whether this window was inherited from the given class name at some point in the inheritance heirarchy.
420
421	\param class_name
422	The class name that is to be checked.
423
424	\return
425	true if this window was inherited from \a class_name. false if not.
426	*/
427	virtual bool testClassName_impl(const String& class_name) const
428	{
429	if (class_name==(const utf8*)"Scrollbar") return true;
430	return Window::testClassName_impl(class_name);
431	}
432
433
434	/*************************************************************************
435	New event handlers for slider widget
436	*************************************************************************/
437	/*!
438	\brief
439	Handler triggered when the scroll position changes
440	*/
441	virtual void onScrollPositionChanged(WindowEventArgs& e);
442
443
444	/*!
445	\brief
446	Handler triggered when the user begins to drag the scroll bar thumb.
447	*/
448	virtual void onThumbTrackStarted(WindowEventArgs& e);
449
450
451	/*!
452	\brief
453	Handler triggered when the scroll bar thumb is released
454	*/
455	virtual void onThumbTrackEnded(WindowEventArgs& e);
456
457
458	/*!
459	\brief
460	Handler triggered when the scroll bar data configuration changes
461	*/
462	virtual void onScrollConfigChanged(WindowEventArgs& e);
463
464
465	/*************************************************************************
466	Overridden event handlers
467	*************************************************************************/
468	virtual void onMouseButtonDown(MouseEventArgs& e);
469	virtual void onSized(WindowEventArgs& e);
470	virtual void onMouseWheel(MouseEventArgs& e);
471
472
473	/*************************************************************************
474	Implementation Data
475	*************************************************************************/
476	float d_documentSize; //!< The size of the document / data being scrolled thorugh.
477	float d_pageSize; //!< The size of a single 'page' of data.
478	float d_stepSize; //!< Step size used for increase / decrease button clicks.
479	float d_overlapSize; //!< Amount of overlap when jumping by a page.
480	float d_position; //!< Current scroll position.
481
482	// Pointers to the controls that make up the scroll bar
483	Thumb* d_thumb; //!< widget used to represent the 'thumb' of the scroll bar.
484	PushButton* d_increase; //!< Widget used for the increase button of the scroll bar.
485	PushButton* d_decrease; //!< Widget used for the decrease button of the scroll bar.
486
487
488	private:
489	/*************************************************************************
490	Static Properties for this class
491	*************************************************************************/
492	static ScrollbarProperties::DocumentSize d_documentSizeProperty;
493	static ScrollbarProperties::PageSize d_pageSizeProperty;
494	static ScrollbarProperties::StepSize d_stepSizeProperty;
495	static ScrollbarProperties::OverlapSize d_overlapSizeProperty;
496	static ScrollbarProperties::ScrollPosition d_scrollPositionProperty;
497
498
499	/*************************************************************************
500	Private methods
501	*************************************************************************/
502	void addScrollbarProperties(void);
503	};
504
505
506	} // End of CEGUI namespace section
507
508	#if defined(_MSC_VER)
509	# pragma warning(pop)
510	#endif
511
512	#endif // end of guard _CEGUIScrollbar_h_

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

Download in other formats: