| // Copyright (C) 2005 Davis E. King ([email protected]) | |
| // License: Boost Software License See LICENSE.txt for the full license. | |
| 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 | |
| }; | |
| // ---------------------------------------------------------------------------------------- | |
| } | |