xref: /haiku/docs/user/interface/ColorControl.dox (revision c5fe2948bac140152522b072003dd99853c485f8)
1/*
2 * Copyright 2011 Haiku, Inc. All rights reserved.
3 * Distributed under the terms of the MIT License.
4 *
5 * Authors:
6 *		John Scipione, jscipione@gmail.com
7 *
8 * Corresponds to:
9 *		headers/os/interface/ColorControl.h	 rev 42794
10 *		src/kits/interface/ColorControl.cpp	 rev 42794
11 */
12
13
14/*!
15	\file ColorControl.h
16	\ingroup interface
17	\ingroup libbe
18	\brief BColorControl class definition and support enums.
19*/
20
21
22/*!
23	\enum color_control_layout
24	\ingroup interface
25
26	Enumeration of the color control layout options.
27
28	\since BeOS R3
29*/
30
31
32/*!
33	\var color_control_layout B_CELLS_4x64
34
35	Cells are arranged in 4 columns, 64 rows.
36
37	\since BeOS R3
38*/
39
40
41/*!
42	\var color_control_layout B_CELLS_8x32
43
44	Cells are arranged in 8 columns, 32 rows.
45
46	\since BeOS R3
47*/
48
49
50/*!
51	\var color_control_layout B_CELLS_16x16
52
53	Cells are arranged in 16 columns, 16 rows.
54
55	\since BeOS R3
56*/
57
58
59/*!
60	\var color_control_layout B_CELLS_32x8
61
62	Cells are arranged in 32 columns, 8 rows.
63
64	\since BeOS R3
65*/
66
67
68/*!
69	\var color_control_layout B_CELLS_64x4
70
71	Cells are arranged in 64 columns, 4 rows.
72
73	\since BeOS R3
74*/
75
76
77/*!
78	\class BColorControl
79	\ingroup interface
80	\ingroup libbe
81
82	\brief BColorControl displays an on-screen color picker.
83
84	The value of the color control is a rgb_color data structure
85	containing a 32-bit color. If a message is specified in the
86	constructor then the message is sent to a target in response to
87	changes in the color value.
88
89	The color value is initially set to 0 which corresponds to black.
90	To set the color of the color control use the SetValue() method.
91
92	An example of creating a color control looks like this:
93\code
94colorControl = new BColorControl(BPoint(0, 0), B_CELLS_32x8, 7.0,
95    "ColorControl", new BMessage(kValueChanged));
96colorControl->SetValue(0x336698);
97\endcode
98
99	A BColorControl contains four color ramps to set the red, green,
100	and blue components of the color control value. A greyscale slider
101	is provided to easily select black, white, and shades of grey. The color
102	control also contains three child BTextControl objects used to set the
103	color by typing in a number between 0 and 255 for the red, green, and
104	blue components of the color value.
105
106	\image html BColorControl_example.png
107
108	If the screen is set to 8-bit (256) colors then the color ramps are
109	replaced with a palette of color cells.
110
111	\image html BColorControl_example_256_colors.png
112
113	You can set the size of these cells by calling the SetCellSize() method.
114
115	\since BeOS R3
116*/
117
118
119/*!
120	\fn BColorControl::BColorControl(BPoint leftTop,
121		color_control_layout layout, float cellSize, const char *name,
122		BMessage* message = NULL, bool useOffscreen = false)
123	\brief Constructs a new color control object.
124
125	\param leftTop location of the left top corner of the frame rectangle
126		relative to the parent view.
127	\param layout The \a layout of the BColorControl. See the
128		#color_control_layout enum for more information. Color control
129		layout options include:
130			- \c B_CELLS_4x64
131			- \c B_CELLS_8x32
132			- \c B_CELLS_16x16
133			- \c B_CELLS_32x8
134			- \c B_CELLS_32x8
135	\param cellSize The size of the sides of the color cell.
136	\param name The name of the color control.
137	\param message The optional \a message to send to a target in response
138		to a change in color value.
139	\param useOffscreen If \c true, all on-screen changes are first
140		made to an off-screen bitmap and then copied to the screen
141		making the drawing smoother, but requiring more memory.
142
143	\since BeOS R3
144*/
145
146
147/*!
148	\fn BColorControl::BColorControl(BMessage* data)
149	\brief Constructs a BColorControl object from an \a data message.
150
151	This method is usually not called directly. If you want to build a
152	color control from a message you should call Instantiate() which can
153	handle errors properly.
154
155	If the \a data deep, the BColorControl object will also undata
156	each of its child views recursively.
157
158	\param data The \a data message to restore from.
159
160	\since BeOS R3
161*/
162
163
164/*!
165	\fn BColorControl::~BColorControl()
166	\brief Destructor method.
167
168	\since BeOS R3
169*/
170
171
172/*!
173	\fn void BColorControl::SetLayout(BLayout* layout)
174	\brief Set the layout of the BColorControl object to \a layout.
175
176	\param layout The \a layout to set.
177
178	\sa BView::SetLayout()
179
180	\since Haiku R1
181*/
182
183
184/*!
185	\fn void BColorControl::SetLayout(color_control_layout layout)
186	\brief Set the layout of the color control.
187
188	Color control layout options include:
189		- \c B_CELLS_4x64
190		- \c B_CELLS_8x32
191		- \c B_CELLS_16x16
192		- \c B_CELLS_32x8
193		- \c B_CELLS_32x8
194
195	\param layout The color control layout to set.
196
197	\since BeOS R3
198*/
199
200
201/*!
202	\fn void BColorControl::SetValue(int32 value)
203	\brief Set the color of the BColorControl to \a value.
204
205	\param value The 32-bit color value to set.
206
207	\since BeOS R3
208*/
209
210
211/*!
212	\fn inline void BColorControl::SetValue(rgb_color color)
213	\brief Set the color of the BColorControl to \a color.
214
215	\param color The rgb_color to set.
216
217	\since BeOS R3
218*/
219
220
221/*!
222	\fn rgb_color BColorControl::ValueAsColor()
223	\brief Return the current color value as an rgb_color.
224
225	\returns The current color as an rgb_color.
226
227	\since BeOS R3
228*/
229
230
231/*!
232	\fn void BColorControl::SetEnabled(bool enabled)
233	\brief Enable and disable the color control.
234
235	\param enabled Whether to enable or disable the color control.
236
237	\since BeOS R3
238*/
239
240
241/*!
242	\fn void BColorControl::AttachedToWindow()
243	\brief Hook method that is called when the object is attached to a
244		window.
245
246	This method also sets the view color and low color of the color control
247	to be the same as its parent's view color and sets the red, green, and
248	blue BTextControl color values.
249
250	\sa BControl::AttachedToWindow()
251	\sa BView::SetViewColor()
252
253	\since BeOS R3
254*/
255
256
257/*!
258	\fn void BColorControl::Draw(BRect updateRect)
259	\brief Draws the area of the color control that intersects \a updateRect.
260
261	\note This is an hook method called by the Interface Kit, you don't
262	have to call it yourself. If you need to forcefully redraw the color
263	control consider calling Invalidate() instead.
264
265	\param updateRect The area to be drawn.
266
267	\sa BView::Draw()
268
269	\since BeOS R3
270*/
271
272
273/*!
274	\fn void BColorControl::SetCellSize(float cellSide)
275	\brief Set the size of the color cell in the color control.
276
277	\param cellSide The cell size to set.
278
279	\since BeOS R3
280*/
281
282
283/*!
284	\fn float BColorControl::CellSize() const
285	\brief Get the current color cell size.
286
287	\returns the current color cell size as a float.
288
289	\since BeOS R3
290*/
291
292
293/*!
294	\fn color_control_layout BColorControl::Layout() const
295	\brief Get the current color control layout.
296
297	\returns The current color_control_layout
298
299	\since BeOS R3
300*/
301
302
303/*!
304	\fn void BColorControl::DetachedFromWindow()
305	\brief Hook method that is called when the object is detached from a
306		window.
307
308	\copydetails BControl::DetachedFromWindow()
309*/
310
311
312/*!
313	\fn void BColorControl::GetPreferredSize(float *_width, float *_height)
314	\brief Fill out the preferred width and height of the checkbox
315		into the \a _width and \a _height parameters.
316
317	\param _width Pointer to a \c float to hold the width of the checkbox.
318	\param _height Pointer to a \c float to hold the height of the checkbox.
319
320	\sa BView::GetPreferredSize()
321
322	\since BeOS R3
323*/
324
325
326/*!
327	\fn void BColorControl::ResizeToPreferred()
328	\brief Resize the color control to its preferred size.
329
330	\sa BView::ResizeToPreferred()
331
332	\since BeOS R3
333*/
334
335
336/*!
337	\fn status_t BColorControl::Invoke(BMessage* message)
338	\brief Tells the messenger to send a message.
339
340	\param message The message to send.
341
342	\sa BControl::Invoke()
343
344	\since BeOS R3
345*/
346
347
348/*!
349	\fn void BColorControl::FrameMoved(BPoint newPosition)
350	\brief Hook method that gets called when the color control is moved.
351
352	\copydetails BView::FrameMoved()
353*/
354
355
356/*!
357	\fn void BColorControl::FrameResized(float newWidth, float newHeight)
358	\brief Hook method that gets called when the checkbox is resized.
359
360	\copydetails BView::FrameResized()
361*/
362
363
364/*!
365	\fn void BColorControl::MakeFocus(bool state)
366	\brief Gives focus to or removes focus from the control.
367
368	\param state \a true to set focus, \a false to remove it.
369
370	\sa BControl::MakeFocus()
371
372	\since BeOS R3
373*/
374
375
376/*!
377	\fn BHandler* BColorControl::ResolveSpecifier(BMessage* message,
378		int32 index, BMessage* specifier, int32 what, const char* property)
379	\copydoc BHandler::ResolveSpecifier()
380*/
381