File size: 25,626 Bytes
9375c9a |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 |
// Copyright (C) 2005 Davis E. King ([email protected])
// License: Boost Software License See LICENSE.txt for the full license.
#undef DLIB_DRAWABLe_ABSTRACT_
#ifdef DLIB_DRAWABLe_ABSTRACT_
#include "../gui_core.h"
#include "fonts_abstract.h"
#include "canvas_drawing_abstract.h"
namespace dlib
{
/*!
GENERAL REMARKS
This file defines the drawable interface class and the drawable_window which
is just a window that is capable of displaying drawable objects (i.e. objects
that implement the drawable interface).
The drawable interface is a simple framework for creating more complex
graphical widgets. It provides a default set of functionality and a
set of events which a gui widget may use.
THREAD SAFETY
All objects and functions defined in this file are thread safe. You may
call them from any thread without serializing access to them.
!*/
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
// class drawable_window
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
class drawable_window : public base_window
{
/*!
WHAT THIS OBJECT REPRESENTS
This object represents a window on the desktop that is capable of
containing drawable objects.
INITIAL STATE
The initial state of the drawable_window is to be hidden. This means
you need to call show() to make it appear.
EVENTS
The drawable_window object uses all the events provided by base_window
except for the on_window_close() event. This means that if you
define handlers for these events yourself you will have to call
the drawable_window's version of them so that the drawable_window
can continue to process and forward these events to its drawable
objects.
!*/
public:
drawable_window (
bool resizable = true,
bool undecorated = false
);
/*!
requires
- if (undecorated == true) then
- resizable == false
ensures
- #*this has been properly initialized
- #background_color() == rgb_pixel(212,208,200)
- if (resizable == true) then
- this window will be resizable by the user
- else
- this window will not be resizable by the user
- if (undecorated == true) then
- this window will not have any graphical elements outside
of its drawable area or appear in the system task bar.
(e.g. a popup menu)
throws
- std::bad_alloc
- dlib::thread_error
- dlib::gui_error
This exception is thrown if there is an error while
creating this window.
!*/
virtual ~drawable_window(
)=0;
/*!
ensures
- if (this window has not already been closed) then
- closes the window
- does NOT trigger the on_window_close() event
- all resources associated with *this have been released
!*/
void set_background_color (
unsigned long red,
unsigned long green,
unsigned long blue
);
/*!
ensures
- #background_color().red == red
- #background_color().green == green
- #background_color().blue == blue
!*/
rgb_pixel background_color (
) const;
/*!
ensures
- returns the background color this window paints its canvas
with before it passes it onto its drawable widgets
!*/
private:
// restricted functions
drawable_window(drawable_window&); // copy constructor
drawable_window& operator=(drawable_window&); // assignment operator
friend class drawable;
};
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
// class drawable
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
enum
{
MOUSE_MOVE = 1,
MOUSE_CLICK = 2,
MOUSE_WHEEL = 4,
WINDOW_RESIZED = 8,
KEYBOARD_EVENTS = 16,
FOCUS_EVENTS = 32,
WINDOW_MOVED = 64,
STRING_PUT = 128
};
class drawable
{
/*!
INITIAL VALUE
top() == 0
left() == 0
right() == -1
bottom() == -1
get_rect().is_empty() == true
is_hidden() == false
is_enabled() == true
z_order() == 0
main_font() == default_font::get_font()
WHAT THIS OBJECT REPRESENTS
This is an interface that all drawable widgets implement. It
provides a standard method (draw()) to draw a widget onto a canvas
and many other convenient functions for drawable objects.
EVENT FORWARDING
All the events that come to a drawable object are forwarded from its
parent window. Additionally, there is no filtering. This means that
if a drawable registers to receive a certain kind of event then whenever
its parent window receives that event the drawable object will get a
forwarded copy of it as well even if the event occurred outside the
drawable's rectangle.
The only events that have anything in the way of filtering are the
draw() and on_user_event() events. draw() is only called on a drawable
object when that object is not hidden. on_user_event() is only called
for drawables that the on_user_event()'s first argument specifically
references. All other events are not filtered at all though.
Z ORDER
Z order defines the order in which drawable objects are drawn. The
lower numbered drawables are drawn first and then the higher numbered
ones. So a drawable with a z order of 0 is drawn before one with a
z order of 1 and so on.
!*/
public:
friend class drawable_window;
drawable (
drawable_window& w,
unsigned long events = 0
) :
m(w.wm),
parent(w),
hidden(false),
enabled(true)
{}
/*!
ensures
- #*this is properly initialized
- #parent_window() == w
- #*this will not receive any events or draw() requests until
enable_events() is called
- once events_are_enabled() == true this drawable will receive
the on_user_event() event. (i.e. you always get this event, you don't
have to enable it by setting something in the events bitset).
- if (events & MOUSE_MOVE) then
- once events_are_enabled() == true this drawable will receive
the following events related to mouse movement: on_mouse_move,
on_mouse_leave, and on_mouse_enter.
- if (events & MOUSE_CLICK) then
- once events_are_enabled() == true this drawable will receive
the following events related to mouse clicks: on_mouse_down and
on_mouse_up.
- if (events & MOUSE_WHEEL) then
- once events_are_enabled() == true this drawable will receive
the following events related to mouse wheel scrolling:
on_wheel_up and on_wheel_down.
- if (events & WINDOW_RESIZED) then
- once events_are_enabled() == true this drawable will receive
the following event related to its parent window resizing:
on_window_resized.
- if (events & KEYBOARD_EVENTS) then
- once events_are_enabled() == true this drawable will receive
the following keyboard event: on_keydown.
- if (events & FOCUS_EVENTS) then
- once events_are_enabled() == true this drawable will receive
the following focus events: on_focus_gained and on_focus_lost.
- if (events & WINDOW_MOVED) then
- once events_are_enabled() == true this drawable will receive
the following event related to its parent window moving:
on_window_moved.
- if (events & STRING_PUT) then
- once events_are_enabled() == true this drawable will receive
the following event related to wide character string input:
on_string_put.
throws
- std::bad_alloc
- dlib::thread_error
!*/
virtual ~drawable (
);
/*!
requires
- events_are_enabled() == false
ensures
- any resources associated with *this have been released
- *this has been removed from its containing window parent_window() and
its parent window will no longer try to dispatch events to it.
Note that this does not trigger a redraw of the parent window. If you
want to do that you must do it yourself.
!*/
long z_order (
) const;
/*!
ensures
- returns the z order for this drawable.
!*/
virtual void set_z_order (
long order
);
/*!
ensures
- #z_order() == order
- if (events_are_enabled() == true) then
- parent_window() is updated to reflect the new state of #*this
throws
- std::bad_alloc
!*/
const rectangle get_rect (
) const;
/*!
ensures
- returns the rectangle that defines the area and position of this
drawable inside its containing window parent_window().
!*/
long bottom (
) const;
/*!
ensures
- returns get_rect().bottom()
!*/
long top (
) const;
/*!
ensures
- returns get_rect().top()
!*/
long left (
) const;
/*!
ensures
- returns get_rect().left()
!*/
long right (
) const;
/*!
ensures
- returns get_rect().right()
!*/
unsigned long width (
) const;
/*!
ensures
- returns get_rect().width()
!*/
unsigned long height (
) const;
/*!
ensures
- returns get_rect().height()
!*/
virtual void set_pos (
long x,
long y
);
/*!
ensures
- #top() == y
- #left() == x
- #width() == width()
- #height() == height()
- if (events_are_enabled() == true) then
- parent_window() is updated to reflect the new state of #*this
- i.e. This just sets the upper left corner of this drawable to the
location (x,y)
!*/
bool is_enabled (
) const;
/*!
ensures
- returns true if this object is enabled and false otherwise.
(it is up to derived classes to define exactly what it means to be
"enabled")
!*/
virtual void enable (
);
/*!
ensures
- #is_enabled() == true
- if (events_are_enabled() == true) then
- parent_window() is updated to reflect the new state of #*this
!*/
virtual void disable (
);
/*!
ensures
- #is_enabled() == false
- if (events_are_enabled() == true) then
- parent_window() is updated to reflect the new state of #*this
!*/
virtual void set_main_font (
const shared_ptr_thread_safe<font>& f
);
/*!
ensures
- #main_font() == f
- if (events_are_enabled() == true) then
- parent_window() is updated to reflect the new state of #*this
!*/
const shared_ptr_thread_safe<font> main_font (
) const;
/*!
ensures
- returns the current main font being used by this widget
!*/
bool is_hidden (
) const;
/*!
ensures
- returns true if this object is NOT currently displayed on parent_window()
and false otherwise.
!*/
virtual void show (
);
/*!
ensures
- #is_hidden() == false
- if (events_are_enabled() == true) then
- parent_window() is updated to reflect the new state of #*this
!*/
virtual void hide (
);
/*!
ensures
- #is_hidden() == true
- if (events_are_enabled() == true) then
- parent_window() is updated to reflect the new state of #*this
!*/
drawable_window& parent_window (
);
/*!
ensures
- returns a reference to the drawable_window that this drawable is
being drawn on and receiving events from.
!*/
const drawable_window& parent_window (
) const;
/*!
ensures
- returns a const reference to the drawable_window that this drawable
is being drawn on and receiving events from.
!*/
virtual int next_free_user_event_number (
)const { return 0; }
/*!
ensures
- returns the smallest number, i, that is the next user event number you
can use in calls to parent.trigger_user_event((void*)this,i).
- This function exists because of the following scenario. Suppose
you make a class called derived1 that inherits from drawable and
in derived1 you use a user event to do something. Then suppose
you inherit from derived1 to make derived2. Now in derived2 you
may want to use a user event to do something as well. How are you
to know which user event numbers are in use already? This function
solves that problem. You would define derived1::next_free_user_event_number()
so that it returned a number bigger than any user event numbers used by
derived1 or its ancestors. Then derived2 could just call
derived1::next_free_user_event_number() to find out what numbers it could use.
!*/
protected:
/*!A drawable_protected_variables
These protected members are provided because they are needed to
implement drawable widgets.
!*/
// This is the rectangle that is returned by get_rect()
rectangle rect;
// This is the mutex used to serialize access to this class.
const rmutex& m;
// This is the parent window of this drawable
drawable_window& parent;
// This is the bool returned by is_hidden()
bool hidden;
// This is the bool returned by is_enabled()
bool enabled;
// This is the font pointer returned by main_font()
shared_ptr_thread_safe<font> mfont;
// This is the x coordinate that we last saw the mouse at or -1 if the mouse
// is outside the parent window.
const long& lastx;
// This is the y coordinate that we last saw the mouse at or -1 if the mouse
// is outside the parent window.
const long& lasty;
void enable_events (
);
/*!
ensures
- #events_are_enabled() == true
!*/
void disable_events (
);
/*!
ensures
- #events_are_enabled() == false
!*/
bool events_are_enabled (
) const;
/*!
ensures
- returns true if this object is receiving events and draw()
requests from its parent window.
- returns false otherwise
!*/
// ---------------- EVENT HANDLERS ------------------
virtual void on_user_event (
int i
){}
/*!
requires
- events_are_enabled() == true
- mutex m is locked
- is called whenever the parent window receives an on_user_event(p,i) event
where p == this. (i.e. this is just a redirect of on_user_event for
cases where the first argument of on_user_event is equal to the
this pointer).
ensures
- does not change the state of mutex m.
!*/
virtual void on_window_resized(
){}
/*!
requires
- events_are_enabled() == true
- mutex m is locked
- this is just the base_window::on_window_resized() event forwarded to
this object. See the gui_core specs for the details about this event.
ensures
- does not change the state of mutex m.
!*/
virtual void on_window_moved(
){}
/*!
requires
- events_are_enabled() == true
- mutex m is locked
- this is just the base_window::on_window_moved() event forwarded to
this object. See the gui_core specs for the details about this event.
ensures
- does not change the state of mutex m.
!*/
virtual void on_mouse_down (
unsigned long btn,
unsigned long state,
long x,
long y,
bool is_double_click
){}
/*!
requires
- events_are_enabled() == true
- mutex m is locked
- this is just the base_window::on_mouse_down() event forwarded to
this object. See the gui_core specs for the details about this event.
ensures
- does not change the state of mutex m.
!*/
virtual void on_mouse_up (
unsigned long btn,
unsigned long state,
long x,
long y
){}
/*!
requires
- events_are_enabled() == true
- mutex m is locked
- this is just the base_window::on_mouse_up() event forwarded to
this object. See the gui_core specs for the details about this event.
ensures
- does not change the state of mutex m.
!*/
virtual void on_mouse_move (
unsigned long state,
long x,
long y
){}
/*!
requires
- events_are_enabled() == true
- mutex m is locked
- x == lastx
- y == lasty
- this is just the base_window::on_mouse_move() event forwarded to
this object. See the gui_core specs for the details about this event.
ensures
- does not change the state of mutex m.
!*/
virtual void on_mouse_leave (
){}
/*!
requires
- events_are_enabled() == true
- mutex m is locked
- this is just the base_window::on_mouse_leave() event forwarded to
this object. See the gui_core specs for the details about this event.
ensures
- does not change the state of mutex m.
!*/
virtual void on_mouse_enter (
){}
/*!
requires
- events_are_enabled() == true
- mutex m is locked
- this is just the base_window::on_mouse_enter() event forwarded to
this object. See the gui_core specs for the details about this event.
ensures
- does not change the state of mutex m.
!*/
virtual void on_wheel_up (
unsigned long state
){}
/*!
requires
- events_are_enabled() == true
- mutex m is locked
- this is just the base_window::on_wheel_up() event forwarded to
this object. See the gui_core specs for the details about this event.
ensures
- does not change the state of mutex m.
!*/
virtual void on_wheel_down (
unsigned long state
){}
/*!
requires
- events_are_enabled() == true
- mutex m is locked
- this is just the base_window::on_wheel_down() event forwarded to
this object. See the gui_core specs for the details about this event.
ensures
- does not change the state of mutex m.
!*/
virtual void on_focus_gained (
){}
/*!
requires
- events_are_enabled() == true
- mutex m is locked
- this is just the base_window::on_focus_gained() event forwarded to
this object. See the gui_core specs for the details about this event.
ensures
- does not change the state of mutex m.
!*/
virtual void on_focus_lost (
){}
/*!
requires
- events_are_enabled() == true
- mutex m is locked
- this is just the base_window::on_focus_lost() event forwarded to
this object. See the gui_core specs for the details about this event.
ensures
- does not change the state of mutex m.
!*/
virtual void on_keydown (
unsigned long key,
bool is_printable,
unsigned long state
){}
/*!
requires
- events_are_enabled() == true
- mutex m is locked
- this is just the base_window::on_keydown() event forwarded to
this object. See the gui_core specs for the details about this event.
ensures
- does not change the state of mutex m.
!*/
virtual void on_string_put (
const std::wstring &str
){}
/*!
requires
- events_are_enabled() == true
- mutex m is locked
- this is just the base_window::on_put_string() event forwarded to
this object. See the gui_core specs for the details about this event.
ensures
- does not change the state of mutex m.
!*/
virtual void draw (
const canvas& c
) const=0;
/*!
requires
- events_are_enabled() == true
- mutex m is locked
- is_hidden() == false
- is called by parent_window() when it needs to repaint itself.
- c == the canvas object for the area of parent_window() that needs
to be repainted.
ensures
- does not change the state of mutex m.
- draws the area of *this that intersects with the canvas onto
the canvas object c.
!*/
private:
// restricted functions
drawable(drawable&); // copy constructor
drawable& operator=(drawable&); // assignment operator
};
// ----------------------------------------------------------------------------------------
}
#endif // DLIB_DRAWABLe_ABSTRACT_
|