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