dlib C++ Library - drawable_abstract.h
// Copyright (C) 2005 Davis E. King (davis@dlib.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_