| 1 | ///////////////////////////////////////////////////////////////////////////// |
| 2 | // Name: pen.h |
| 3 | // Purpose: interface of wxPen* classes |
| 4 | // Author: wxWidgets team |
| 5 | // RCS-ID: $Id$ |
| 6 | // Licence: wxWindows licence |
| 7 | ///////////////////////////////////////////////////////////////////////////// |
| 8 | |
| 9 | /** |
| 10 | The possible styles for a wxPen. |
| 11 | |
| 12 | Note that hatched pen styles are not supported by X11-based ports, |
| 13 | including wxGTK. |
| 14 | */ |
| 15 | enum wxPenStyle |
| 16 | { |
| 17 | wxPENSTYLE_INVALID = -1, |
| 18 | |
| 19 | wxPENSTYLE_SOLID, |
| 20 | /**< Solid style. */ |
| 21 | |
| 22 | wxPENSTYLE_DOT, |
| 23 | /**< Dotted style. */ |
| 24 | |
| 25 | wxPENSTYLE_LONG_DASH, |
| 26 | /**< Long dashed style. */ |
| 27 | |
| 28 | wxPENSTYLE_SHORT_DASH, |
| 29 | /**< Short dashed style. */ |
| 30 | |
| 31 | wxPENSTYLE_DOT_DASH, |
| 32 | /**< Dot and dash style. */ |
| 33 | |
| 34 | wxPENSTYLE_USER_DASH, |
| 35 | /**< Use the user dashes: see wxPen::SetDashes. */ |
| 36 | |
| 37 | wxPENSTYLE_TRANSPARENT, |
| 38 | /**< No pen is used. */ |
| 39 | |
| 40 | wxPENSTYLE_STIPPLE_MASK_OPAQUE, |
| 41 | /**< @todo WHAT's this? */ |
| 42 | |
| 43 | wxPENSTYLE_STIPPLE_MASK, |
| 44 | /**< @todo WHAT's this? */ |
| 45 | |
| 46 | wxPENSTYLE_STIPPLE, |
| 47 | /**< Use the stipple bitmap. */ |
| 48 | |
| 49 | wxPENSTYLE_BDIAGONAL_HATCH, |
| 50 | /**< Backward diagonal hatch. */ |
| 51 | |
| 52 | wxPENSTYLE_CROSSDIAG_HATCH, |
| 53 | /**< Cross-diagonal hatch. */ |
| 54 | |
| 55 | wxPENSTYLE_FDIAGONAL_HATCH, |
| 56 | /**< Forward diagonal hatch. */ |
| 57 | |
| 58 | wxPENSTYLE_CROSS_HATCH, |
| 59 | /**< Cross hatch. */ |
| 60 | |
| 61 | wxPENSTYLE_HORIZONTAL_HATCH, |
| 62 | /**< Horizontal hatch. */ |
| 63 | |
| 64 | wxPENSTYLE_VERTICAL_HATCH, |
| 65 | /**< Vertical hatch. */ |
| 66 | |
| 67 | wxPENSTYLE_FIRST_HATCH = wxPENSTYLE_BDIAGONAL_HATCH, |
| 68 | wxPENSTYLE_LAST_HATCH = wxPENSTYLE_VERTICAL_HATCH |
| 69 | }; |
| 70 | |
| 71 | /** |
| 72 | The possible join values of a wxPen. |
| 73 | |
| 74 | @todo use wxPENJOIN_ prefix |
| 75 | */ |
| 76 | enum wxPenJoin |
| 77 | { |
| 78 | wxJOIN_INVALID = -1, |
| 79 | |
| 80 | wxJOIN_BEVEL = 120, |
| 81 | wxJOIN_MITER, |
| 82 | wxJOIN_ROUND, |
| 83 | }; |
| 84 | |
| 85 | |
| 86 | /** |
| 87 | The possible cap values of a wxPen. |
| 88 | |
| 89 | @todo use wxPENCAP_ prefix |
| 90 | */ |
| 91 | enum wxPenCap |
| 92 | { |
| 93 | wxCAP_INVALID = -1, |
| 94 | |
| 95 | wxCAP_ROUND = 130, |
| 96 | wxCAP_PROJECTING, |
| 97 | wxCAP_BUTT |
| 98 | }; |
| 99 | |
| 100 | |
| 101 | |
| 102 | /** |
| 103 | @class wxPen |
| 104 | |
| 105 | A pen is a drawing tool for drawing outlines. It is used for drawing |
| 106 | lines and painting the outline of rectangles, ellipses, etc. |
| 107 | It has a colour, a width and a style. |
| 108 | |
| 109 | @note On a monochrome display, wxWidgets shows all non-white pens as black. |
| 110 | |
| 111 | Do not initialize objects on the stack before the program commences, |
| 112 | since other required structures may not have been set up yet. |
| 113 | Instead, define global pointers to objects and create them in wxApp::OnInit() |
| 114 | or when required. |
| 115 | |
| 116 | An application may wish to dynamically create pens with different characteristics, |
| 117 | and there is the consequent danger that a large number of duplicate pens will |
| 118 | be created. Therefore an application may wish to get a pointer to a pen by using |
| 119 | the global list of pens ::wxThePenList, and calling the member function |
| 120 | wxPenList::FindOrCreatePen(). |
| 121 | See wxPenList for more info. |
| 122 | |
| 123 | This class uses @ref overview_refcount "reference counting and copy-on-write" internally |
| 124 | so that assignments between two instances of this class are very cheap. |
| 125 | You can therefore use actual objects instead of pointers without efficiency problems. |
| 126 | If an instance of this class is changed it will create its own data internally |
| 127 | so that other instances, which previously shared the data using the reference |
| 128 | counting, are not affected. |
| 129 | |
| 130 | @library{wxcore} |
| 131 | @category{gdi} |
| 132 | |
| 133 | @stdobjects |
| 134 | @li ::wxNullPen |
| 135 | @li ::wxBLACK_DASHED_PEN |
| 136 | @li ::wxBLACK_PEN |
| 137 | @li ::wxBLUE_PEN |
| 138 | @li ::wxCYAN_PEN |
| 139 | @li ::wxGREEN_PEN |
| 140 | @li ::wxYELLOW_PEN |
| 141 | @li ::wxGREY_PEN |
| 142 | @li ::wxLIGHT_GREY_PEN |
| 143 | @li ::wxMEDIUM_GREY_PEN |
| 144 | @li ::wxRED_PEN |
| 145 | @li ::wxTRANSPARENT_PEN |
| 146 | @li ::wxWHITE_PEN |
| 147 | |
| 148 | @see wxPenList, wxDC, wxDC::SetPen() |
| 149 | */ |
| 150 | class wxPen : public wxGDIObject |
| 151 | { |
| 152 | public: |
| 153 | /** |
| 154 | Default constructor. The pen will be uninitialised, and IsOk() will return @false. |
| 155 | */ |
| 156 | wxPen(); |
| 157 | |
| 158 | /** |
| 159 | Constructs a pen from a colour object, pen width and style. |
| 160 | |
| 161 | @param colour |
| 162 | A colour object. |
| 163 | @param width |
| 164 | Pen width. Under Windows, the pen width cannot be greater than 1 if |
| 165 | the style is @c wxPENSTYLE_DOT, @c wxPENSTYLE_LONG_DASH, @c wxPENSTYLE_SHORT_DASH, |
| 166 | @c wxPENSTYLE_DOT_DASH, or @c wxPENSTYLE_USER_DASH. |
| 167 | @param style |
| 168 | The style may be one of the ::wxPenStyle values. |
| 169 | |
| 170 | @remarks Different versions of Windows and different versions of other |
| 171 | platforms support very different subsets of the styles above |
| 172 | - there is no similarity even between Windows95 and Windows98 - |
| 173 | so handle with care. |
| 174 | |
| 175 | @see SetStyle(), SetColour(), SetWidth() |
| 176 | */ |
| 177 | wxPen(const wxColour& colour, int width = 1, wxPenStyle style = wxPENSTYLE_SOLID); |
| 178 | |
| 179 | /** |
| 180 | Constructs a stippled pen from a stipple bitmap and a width. |
| 181 | |
| 182 | @param width |
| 183 | Pen width. Under Windows, the pen width cannot be greater than 1 if |
| 184 | the style is @c wxPENSTYLE_DOT, @c wxPENSTYLE_LONG_DASH, @c wxPENSTYLE_SHORT_DASH, |
| 185 | @c wxPENSTYLE_DOT_DASH, or @c wxPENSTYLE_USER_DASH. |
| 186 | @param stipple |
| 187 | A stipple bitmap. |
| 188 | |
| 189 | @onlyfor{wxmsw,wxosx} |
| 190 | |
| 191 | @see SetWidth(), SetStipple() |
| 192 | */ |
| 193 | wxPen(const wxBitmap& stipple, int width); |
| 194 | |
| 195 | /** |
| 196 | Copy constructor, uses @ref overview_refcount. |
| 197 | |
| 198 | @param pen |
| 199 | A pointer or reference to a pen to copy. |
| 200 | */ |
| 201 | wxPen(const wxPen& pen); |
| 202 | |
| 203 | /** |
| 204 | Destructor. |
| 205 | @see @ref overview_refcount_destruct "reference-counted object destruction" |
| 206 | |
| 207 | @remarks Although all remaining pens are deleted when the application |
| 208 | exits, the application should try to clean up all pens |
| 209 | itself. This is because wxWidgets cannot know if a |
| 210 | pointer to the pen object is stored in an application |
| 211 | data structure, and there is a risk of double deletion. |
| 212 | */ |
| 213 | virtual ~wxPen(); |
| 214 | |
| 215 | /** |
| 216 | Returns the pen cap style, which may be one of @c wxCAP_ROUND, |
| 217 | @c wxCAP_PROJECTING and @c wxCAP_BUTT. |
| 218 | |
| 219 | The default is @c wxCAP_ROUND. |
| 220 | |
| 221 | @see SetCap() |
| 222 | */ |
| 223 | virtual wxPenCap GetCap() const; |
| 224 | |
| 225 | /** |
| 226 | Returns a reference to the pen colour. |
| 227 | |
| 228 | @see SetColour() |
| 229 | */ |
| 230 | virtual wxColour GetColour() const; |
| 231 | |
| 232 | /** |
| 233 | Gets an array of dashes (defined as @c char in X, @c DWORD under Windows). |
| 234 | @a dashes is a pointer to the internal array. Do not deallocate or store this |
| 235 | pointer. |
| 236 | |
| 237 | @return The number of dashes associated with this pen. |
| 238 | |
| 239 | @see SetDashes() |
| 240 | */ |
| 241 | virtual int GetDashes(wxDash** dashes) const; |
| 242 | |
| 243 | /** |
| 244 | Returns the pen join style, which may be one of @c wxJOIN_BEVEL, |
| 245 | @c wxJOIN_ROUND and @c wxJOIN_MITER. |
| 246 | |
| 247 | The default is @c wxJOIN_ROUND. |
| 248 | |
| 249 | @see SetJoin() |
| 250 | */ |
| 251 | virtual wxPenJoin GetJoin() const; |
| 252 | |
| 253 | /** |
| 254 | Gets a pointer to the stipple bitmap. |
| 255 | |
| 256 | @see SetStipple() |
| 257 | */ |
| 258 | virtual wxBitmap* GetStipple() const; |
| 259 | |
| 260 | /** |
| 261 | Returns the pen style. |
| 262 | |
| 263 | @see wxPen(), SetStyle() |
| 264 | */ |
| 265 | virtual wxPenStyle GetStyle() const; |
| 266 | |
| 267 | /** |
| 268 | Returns the pen width. |
| 269 | |
| 270 | @see SetWidth() |
| 271 | */ |
| 272 | virtual int GetWidth() const; |
| 273 | |
| 274 | /** |
| 275 | Returns @true if the pen is initialised. |
| 276 | |
| 277 | Notice that an uninitialized pen object can't be queried for any pen |
| 278 | properties and all calls to the accessor methods on it will result in |
| 279 | an assert failure. |
| 280 | */ |
| 281 | virtual bool IsOk() const; |
| 282 | |
| 283 | /** |
| 284 | Returns @true if the pen is a valid non-transparent pen. |
| 285 | |
| 286 | This method returns @true if the pen object is initialized and has a |
| 287 | non-transparent style. Notice that this should be used instead of |
| 288 | simply testing whether GetStyle() returns a style different from |
| 289 | wxPENSTYLE_TRANSPARENT if the pen may be invalid as GetStyle() would |
| 290 | assert in this case. |
| 291 | |
| 292 | @see IsTransparent() |
| 293 | |
| 294 | @since 2.9.2. |
| 295 | */ |
| 296 | bool IsNonTransparent() const; |
| 297 | |
| 298 | /** |
| 299 | Returns @true if the pen is transparent. |
| 300 | |
| 301 | A transparent pen is simply a pen with wxPENSTYLE_TRANSPARENT style. |
| 302 | |
| 303 | Notice that this function works even for non-initialized pens (for |
| 304 | which it returns @false) unlike tests of the form <code>GetStyle() == |
| 305 | wxPENSTYLE_TRANSPARENT</code> which would assert if the pen is invalid. |
| 306 | |
| 307 | @see IsNonTransparent() |
| 308 | |
| 309 | @since 2.9.2. |
| 310 | */ |
| 311 | bool IsTransparent() const; |
| 312 | |
| 313 | /** |
| 314 | Sets the pen cap style, which may be one of @c wxCAP_ROUND, @c wxCAP_PROJECTING |
| 315 | and @c wxCAP_BUTT. The default is @c wxCAP_ROUND. |
| 316 | |
| 317 | @see GetCap() |
| 318 | */ |
| 319 | virtual void SetCap(wxPenCap capStyle); |
| 320 | |
| 321 | //@{ |
| 322 | /** |
| 323 | The pen's colour is changed to the given colour. |
| 324 | |
| 325 | @see GetColour() |
| 326 | */ |
| 327 | virtual void SetColour(wxColour& colour); |
| 328 | virtual void SetColour(unsigned char red, unsigned char green, unsigned char blue); |
| 329 | //@} |
| 330 | |
| 331 | /** |
| 332 | Associates an array of pointers to dashes (defined as @c char in X, @c DWORD under |
| 333 | Windows) with the pen. |
| 334 | |
| 335 | The array is not deallocated by wxPen, but neither must it be deallocated by |
| 336 | the calling application until the pen is deleted or this function is called |
| 337 | with a @NULL array. |
| 338 | |
| 339 | @see GetDashes() |
| 340 | */ |
| 341 | virtual void SetDashes(int n, const wxDash* dash); |
| 342 | |
| 343 | /** |
| 344 | Sets the pen join style, which may be one of @c wxJOIN_BEVEL, @c wxJOIN_ROUND |
| 345 | and @c wxJOIN_MITER. |
| 346 | |
| 347 | The default is @c wxJOIN_ROUND. |
| 348 | |
| 349 | @see GetJoin() |
| 350 | */ |
| 351 | virtual void SetJoin(wxPenJoin join_style); |
| 352 | |
| 353 | /** |
| 354 | Sets the bitmap for stippling. |
| 355 | |
| 356 | @see GetStipple() |
| 357 | */ |
| 358 | virtual void SetStipple(const wxBitmap& stipple); |
| 359 | |
| 360 | /** |
| 361 | Set the pen style. |
| 362 | |
| 363 | @see wxPen() |
| 364 | */ |
| 365 | virtual void SetStyle(wxPenStyle style); |
| 366 | |
| 367 | /** |
| 368 | Sets the pen width. |
| 369 | |
| 370 | @see GetWidth() |
| 371 | */ |
| 372 | virtual void SetWidth(int width); |
| 373 | |
| 374 | /** |
| 375 | Inequality operator. |
| 376 | |
| 377 | See @ref overview_refcount_equality "reference-counted object comparison" for |
| 378 | more info. |
| 379 | */ |
| 380 | bool operator!=(const wxPen& pen) const; |
| 381 | |
| 382 | /** |
| 383 | Assignment operator, using @ref overview_refcount. |
| 384 | */ |
| 385 | wxPen& operator=(const wxPen& pen); |
| 386 | |
| 387 | /** |
| 388 | Equality operator. |
| 389 | |
| 390 | See @ref overview_refcount_equality "reference-counted object comparison" for |
| 391 | more info. |
| 392 | */ |
| 393 | bool operator==(const wxPen& pen) const; |
| 394 | }; |
| 395 | |
| 396 | /** |
| 397 | An empty pen. |
| 398 | wxPen::IsOk() always returns @false for this object. |
| 399 | */ |
| 400 | wxPen wxNullPen; |
| 401 | |
| 402 | /** |
| 403 | Red pen. |
| 404 | Except for the color it has all standard attributes |
| 405 | (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...). |
| 406 | */ |
| 407 | wxPen* wxRED_PEN; |
| 408 | |
| 409 | /** |
| 410 | Blue pen. |
| 411 | Except for the color it has all standard attributes |
| 412 | (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...). |
| 413 | */ |
| 414 | wxPen* wxBLUE_PEN; |
| 415 | |
| 416 | /** |
| 417 | Cyan pen. |
| 418 | Except for the color it has all standard attributes |
| 419 | (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...). |
| 420 | */ |
| 421 | wxPen* wxCYAN_PEN; |
| 422 | |
| 423 | /** |
| 424 | Green pen. |
| 425 | Except for the color it has all standard attributes |
| 426 | (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...). |
| 427 | */ |
| 428 | wxPen* wxGREEN_PEN; |
| 429 | |
| 430 | /** |
| 431 | Yellow pen. |
| 432 | Except for the color it has all standard attributes |
| 433 | (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...). |
| 434 | */ |
| 435 | wxPen* wxYELLOW_PEN; |
| 436 | |
| 437 | /** |
| 438 | Black pen. |
| 439 | Except for the color it has all standard attributes |
| 440 | (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...). |
| 441 | */ |
| 442 | wxPen* wxBLACK_PEN; |
| 443 | |
| 444 | /** |
| 445 | White pen. |
| 446 | Except for the color it has all standard attributes |
| 447 | (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...). |
| 448 | */ |
| 449 | wxPen* wxWHITE_PEN; |
| 450 | |
| 451 | /** |
| 452 | Transparent pen. |
| 453 | Except for the color it has all standard attributes |
| 454 | (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...). |
| 455 | */ |
| 456 | wxPen* wxTRANSPARENT_PEN; |
| 457 | |
| 458 | /** |
| 459 | Black dashed pen. |
| 460 | Except for the color and for the @c wxPENSTYLE_SHORT_DASH it has all standard attributes |
| 461 | (1-pixel width, @c wxCAP_ROUND style, etc...). |
| 462 | */ |
| 463 | wxPen* wxBLACK_DASHED_PEN; |
| 464 | |
| 465 | /** |
| 466 | Grey pen. |
| 467 | Except for the color it has all standard attributes |
| 468 | (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...). |
| 469 | */ |
| 470 | wxPen* wxGREY_PEN; |
| 471 | |
| 472 | /** |
| 473 | Medium-grey pen. |
| 474 | Except for the color it has all standard attributes |
| 475 | (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...). |
| 476 | */ |
| 477 | wxPen* wxMEDIUM_GREY_PEN; |
| 478 | |
| 479 | /** |
| 480 | Light-grey pen. |
| 481 | Except for the color it has all standard attributes |
| 482 | (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...). |
| 483 | */ |
| 484 | wxPen* wxLIGHT_GREY_PEN; |
| 485 | |
| 486 | |
| 487 | |
| 488 | /** |
| 489 | @class wxPenList |
| 490 | |
| 491 | There is only one instance of this class: ::wxThePenList. |
| 492 | Use this object to search for a previously created pen of the desired |
| 493 | type and create it if not already found. In some windowing systems, |
| 494 | the pen may be a scarce resource, so it can pay to reuse old |
| 495 | resources if possible. When an application finishes, all pens will |
| 496 | be deleted and their resources freed, eliminating the possibility of |
| 497 | 'memory leaks'. However, it is best not to rely on this automatic |
| 498 | cleanup because it can lead to double deletion in some circumstances. |
| 499 | |
| 500 | There are two mechanisms in recent versions of wxWidgets which make the |
| 501 | pen list less useful than it once was. Under Windows, scarce resources |
| 502 | are cleaned up internally if they are not being used. Also, a referencing |
| 503 | counting mechanism applied to all GDI objects means that some sharing |
| 504 | of underlying resources is possible. You don't have to keep track of pointers, |
| 505 | working out when it is safe delete a pen, because the referencing counting does |
| 506 | it for you. For example, you can set a pen in a device context, and then |
| 507 | immediately delete the pen you passed, because the pen is 'copied'. |
| 508 | |
| 509 | So you may find it easier to ignore the pen list, and instead create |
| 510 | and copy pens as you see fit. If your Windows resource meter suggests |
| 511 | your application is using too many resources, you can resort to using |
| 512 | GDI lists to share objects explicitly. |
| 513 | |
| 514 | The only compelling use for the pen list is for wxWidgets to keep |
| 515 | track of pens in order to clean them up on exit. It is also kept for |
| 516 | backward compatibility with earlier versions of wxWidgets. |
| 517 | |
| 518 | @library{wxcore} |
| 519 | @category{gdi} |
| 520 | |
| 521 | @stdobjects |
| 522 | ::wxThePenList |
| 523 | |
| 524 | @see wxPen |
| 525 | */ |
| 526 | class wxPenList |
| 527 | { |
| 528 | public: |
| 529 | /** |
| 530 | Constructor. The application should not construct its own pen list: |
| 531 | use the object pointer ::wxThePenList. |
| 532 | */ |
| 533 | wxPenList(); |
| 534 | |
| 535 | /** |
| 536 | Finds a pen with the specified attributes and returns it, else creates a |
| 537 | new pen, adds it to the pen list, and returns it. |
| 538 | |
| 539 | @param colour |
| 540 | Colour object. |
| 541 | @param width |
| 542 | Width of pen. |
| 543 | @param style |
| 544 | Pen style. See ::wxPenStyle for a list of styles. |
| 545 | */ |
| 546 | wxPen* FindOrCreatePen(const wxColour& colour, |
| 547 | int width = 1, |
| 548 | wxPenStyle style = wxPENSTYLE_SOLID); |
| 549 | }; |
| 550 | |
| 551 | /** |
| 552 | The global list of wxPen objects ready to be re-used (for better performances). |
| 553 | */ |
| 554 | wxPenList* wxThePenList; |
| 555 | |