dlib C++ Library - drawable_abstract.h

    // Copyright (C) 2005  Davis E. King (davisking@users.sourceforge.net)
    // 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_