// Copyright (C) 2005 Davis E. King (davis@dlib.net), Keita Mochizuki
// License: Boost Software License See LICENSE.txt for the full license.
#undef DLIB_BASE_WIDGETs_ABSTRACT_
#ifdef DLIB_BASE_WIDGETs_ABSTRACT_
#include "fonts_abstract.h"
#include "drawable_abstract.h"
#include "../gui_core.h"
#include <string>
namespace dlib
{
/*!
GENERAL REMARKS
This file contains objects that are useful for creating complex drawable
widgets.
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.
EVENT HANDLERS
If you derive from any of the drawable objects and redefine any of the on_*()
event handlers then you should ensure that your version calls the same event
handler in the base object so that the base class part of your object will also
be able to process the event.
Also note that all event handlers, including the user registered callback
functions, are executed in the event handling thread. Additionally,
the drawable::m mutex will always be locked while these event handlers
are running. Also, don't rely on get_thread_id() always returning the
same ID from inside event handlers.
!*/
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
// class draggable
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
class draggable : public drawable
{
/*!
INITIAL VALUE
draggable_area() == an initial value for its type
WHAT THIS OBJECT REPRESENTS
This object represents a drawable object that is draggable by the mouse.
You use it by inheriting from it and defining the draw() method and any
of the on_*() event handlers you need.
This object is draggable by the user when is_enabled() == true and
not draggable otherwise.
!*/
public:
draggable(
drawable_window& w,
unsigned long events = 0
);
/*!
ensures
- #*this is properly initialized
- #*this has been added to window w
- #parent_window() == w
- This object will not receive any events or draw() requests until
enable_events() is called
- the events flags are passed on to the drawable object's
constructor.
throws
- std::bad_alloc
- dlib::thread_error
!*/
virtual ~draggable(
) = 0;
/*!
ensures
- all resources associated with *this have been released
!*/
rectangle draggable_area (
) const;
/*!
ensures
- returns the area that this draggable can be dragged around in.
!*/
void set_draggable_area (
const rectangle& area
);
/*!
ensures
- #draggable_area() == area
!*/
protected:
bool is_being_dragged (
) const;
/*!
requires
- mutex drawable::m is locked
ensures
- if (this widget is currently being dragged by the user) then
- returns true
- else
- returns false
!*/
// does nothing by default
virtual void on_drag (
){}
/*!
requires
- enable_events() has been called
- is_enabled() == true
- is_hidden() == false
- mutex drawable::m is locked
- is called when the user drags this object
- get_rect() == the rectangle that defines the new position
of this object.
- is_being_dragged() == true
ensures
- does not change the state of mutex drawable::m.
!*/
// does nothing by default
virtual void on_drag_stop (
){}
/*!
requires
- enable_events() has been called
- mutex drawable::m is locked
- is called when the user stops dragging this object
- is_being_dragged() == false
ensures
- does not change the state of mutex drawable::m.
!*/
private:
// restricted functions
draggable(draggable&); // copy constructor
draggable& operator=(draggable&); // assignment operator
};
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
// class mouse_over_event
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
class mouse_over_event : public drawable
{
/*!
INITIAL VALUE
is_mouse_over() == false
WHAT THIS OBJECT REPRESENTS
This object represents a drawable object with the addition of two events
that will alert you when the mouse enters or leaves your drawable object.
You use it by inheriting from it and defining the draw() method and any
of the on_*() event handlers you need.
!*/
public:
mouse_over_event(
drawable_window& w,
unsigned long events = 0
);
/*!
ensures
- #*this is properly initialized
- #*this has been added to window w
- #parent_window() == w
- #*this will not receive any events or draw() requests until
enable_events() is called
- the events flags are passed on to the drawable object's
constructor.
throws
- std::bad_alloc
- dlib::thread_error
!*/
virtual ~mouse_over_event(
) = 0;
/*!
ensures
- all resources associated with *this have been released
!*/
protected:
bool is_mouse_over (
) const;
/*!
requires
- mutex drawable::m is locked
ensures
- if (the mouse is currently over this widget) then
- returns true
- else
- returns false
!*/
// does nothing by default
virtual void on_mouse_over (
){}
/*!
requires
- enable_events() has been called
- mutex drawable::m is locked
- is_enabled() == true
- is_hidden() == false
- is called whenever this object transitions from the state where
is_mouse_over() == false to is_mouse_over() == true
ensures
- does not change the state of mutex drawable::m.
!*/
// does nothing by default
virtual void on_mouse_not_over (
){}
/*!
requires
- enable_events() has been called
- mutex drawable::m is locked
- is called whenever this object transitions from the state where
is_mouse_over() == true to is_mouse_over() == false
ensures
- does not change the state of mutex drawable::m.
!*/
private:
// restricted functions
mouse_over_event(mouse_over_event&); // copy constructor
mouse_over_event& operator=(mouse_over_event&); // assignment operator
};
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
// class button_action
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
class button_action : public mouse_over_event
{
/*!
INITIAL VALUE
is_depressed() == false
WHAT THIS OBJECT REPRESENTS
This object represents the clicking action of a push button. It provides
simple callbacks that can be used to make various kinds of button
widgets.
You use it by inheriting from it and defining the draw() method and any
of the on_*() event handlers you need.
!*/
public:
button_action(
drawable_window& w,
unsigned long events = 0
);
/*!
ensures
- #*this is properly initialized
- #*this has been added to window w
- #parent_window() == w
- #*this will not receive any events or draw() requests until
enable_events() is called
- the events flags are passed on to the drawable object's
constructor.
throws
- std::bad_alloc
- dlib::thread_error
!*/
virtual ~button_action(
) = 0;
/*!
ensures
- all resources associated with *this have been released
!*/
protected:
bool is_depressed (
) const;
/*!
requires
- mutex drawable::m is locked
ensures
- if (this button is currently in a depressed state) then
- the user has left clicked on this drawable and is still
holding the left mouse button down over it.
- returns true
- else
- returns false
!*/
// does nothing by default
virtual void on_button_down (
){}
/*!
requires
- enable_events() has been called
- mutex drawable::m is locked
- is_enabled() == true
- is_hidden() == false
- the area in parent_window() defined by get_rect() has been invalidated.
(This means you don't have to call invalidate_rectangle())
- is called whenever this object transitions from the state where
is_depressed() == false to is_depressed() == true
ensures
- does not change the state of mutex drawable::m.
!*/
// does nothing by default
virtual void on_button_up (
bool mouse_over
){}
/*!
requires
- enable_events() has been called
- mutex drawable::m is locked
- the area in parent_window() defined by get_rect() has been invalidated.
(This means you don't have to call invalidate_rectangle())
- is called whenever this object transitions from the state where
is_depressed() == true to is_depressed() == false
- if (the mouse was over this button when this event occurred) then
- mouse_over == true
- else
- mouse_over == false
ensures
- does not change the state of mutex drawable::m.
!*/
private:
// restricted functions
button_action(button_action&); // copy constructor
button_action& operator=(button_action&); // assignment operator
};
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
// class button
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
class button : public button_action
{
/*!
INITIAL VALUE
name() == ""
tooltip_text() == "" (i.e. there is no tooltip by default)
WHAT THIS OBJECT REPRESENTS
This object represents a simple button.
When this object is disabled it means it will not respond to user clicks.
!*/
public:
button(
drawable_window& w
);
/*!
ensures
- #*this is properly initialized
- #*this has been added to window w
- #parent_window() == w
throws
- std::bad_alloc
- dlib::thread_error
!*/
virtual ~button(
);
/*!
ensures
- all resources associated with *this have been released
!*/
void set_size (
unsigned long width_,
unsigned long height_
);
/*!
ensures
- if (width and height are big enough to contain the name of this button) then
- #width() == width_
- #height() == height_
- #top() == top()
- #left() == left()
- i.e. The location of the upper left corner of this button stays the
same but its width and height are modified
!*/
void set_name (const std::wstring& name);
void set_name (const dlib::ustring& name);
void set_name (
const std::string& name
);
/*!
ensures
- #name() == name
- this button has been resized such that it is big enough to contain
the new name.
throws
- std::bad_alloc
!*/
const std::wstring wname () const;
const dlib::string uname () const;
const std::string name (
) const;
/*!
ensures
- returns the name of this button
throws
- std::bad_alloc
!*/
void set_tooltip_text (const std::wstring& text);
void set_tooltip_text (const dlib::ustring& text);
void set_tooltip_text (
const std::string& text
);
/*!
ensures
- #tooltip_text() == text
- enables the tooltip for this button
!*/
const dlib::ustring tooltip_utext () const;
const std::wstring tooltip_wtext () const;
const std::string tooltip_text (
) const;
/*!
ensures
- returns the text that is displayed in the tooltip for this button
!*/
bool is_depressed (
) const;
/*!
ensures
- if (this button is currently in a depressed state) then
- the user has left clicked on this widget and is still
holding the left mouse button down over it.
- returns true
- else
- returns false
!*/
template <
typename style_type
>
void set_style (
const style_type& style
);
/*!
requires
- style_type == a type that inherits from button_style
ensures
- this button object will draw itself using the given
button style
!*/
template <
typename T
>
void set_click_handler (
T& object,
void (T::*event_handler)()
);
/*!
requires
- event_handler is a valid pointer to a member function in T
ensures
- the event_handler function is called on object when the button is
clicked by the user.
- any previous calls to this function are overridden by this new call.
(i.e. you can only have one event handler associated with this
event at a time)
throws
- std::bad_alloc
!*/
void set_click_handler (
const any_function<void()>& event_handler
);
/*!
ensures
- the event_handler function is called when the button is clicked by
the user.
- any previous calls to this function are overridden by this new call.
(i.e. you can only have one event handler associated with this
event at a time)
throws
- std::bad_alloc
!*/
template <
typename T
>
void set_click_handler (
T& object,
void (T::*event_handler)(button& self)
);
/*!
requires
- event_handler is a valid pointer to a member function in T
ensures
- &self == this
- the event_handler function is called on object when the button is
clicked by the user.
- any previous calls to this function are overridden by this new call.
(i.e. you can only have one event handler associated with this
event at a time)
throws
- std::bad_alloc
!*/
void set_sourced_click_handler (
const any_function<void(button& self)>& event_handler
);
/*!
ensures
- &self == this
- the event_handler function is called when the button is clicked by
the user.
- any previous calls to this function are overridden by this new call.
(i.e. you can only have one event handler associated with this
event at a time)
throws
- std::bad_alloc
!*/
template <
typename T
>
void set_button_down_handler (
T& object,
void (T::*event_handler)()
);
/*!
requires
- event_handler is a valid pointer to a member function in T
ensures
- the event_handler function is called on object when the user causes
the button to go into its depressed state.
- any previous calls to this function are overridden by this new call.
(i.e. you can only have one event handler associated with this
event at a time)
throws
- std::bad_alloc
!*/
void set_button_down_handler (
const any_function<void()>& event_handler
);
/*!
ensures
- the event_handler function is called when the user causes the button
to go into its depressed state.
- any previous calls to this function are overridden by this new call.
(i.e. you can only have one event handler associated with this
event at a time)
throws
- std::bad_alloc
!*/
template <
typename T
>
void set_button_up_handler (
T& object,
void (T::*event_handler)(bool mouse_over)
);
/*!
requires
- event_handler is a valid pointer to a member function in T
ensures
- the event_handler function is called on object when the user causes
the button to go into its non-depressed state.
- if (the mouse is over this button when this event occurs) then
- mouse_over == true
- else
- mouse_over == false
- any previous calls to this function are overridden by this new call.
(i.e. you can only have one event handler associated with this
event at a time)
throws
- std::bad_alloc
!*/
void set_button_up_handler (
const any_function<void(bool mouse_over)>& event_handler
);
/*!
ensures
- the event_handler function is called when the user causes the
button to go into its non-depressed state.
- if (the mouse is over this button when this event occurs) then
- mouse_over == true
- else
- mouse_over == false
- any previous calls to this function are overridden by this new call.
(i.e. you can only have one event handler associated with this
event at a time)
throws
- std::bad_alloc
!*/
template <
typename T
>
void set_button_down_handler (
T& object,
void (T::*event_handler)(button& self)
);
/*!
requires
- event_handler is a valid pointer to a member function in T
ensures
- &self == this
- the event_handler function is called on object when the user causes
the button to go into its depressed state.
- any previous calls to this function are overridden by this new call.
(i.e. you can only have one event handler associated with this
event at a time)
throws
- std::bad_alloc
!*/
void set_sourced_button_down_handler (
const any_function<void(button& self)>& event_handler
);
/*!
ensures
- &self == this
- the event_handler function is called when the user causes the button
to go into its depressed state.
- any previous calls to this function are overridden by this new call.
(i.e. you can only have one event handler associated with this
event at a time)
throws
- std::bad_alloc
!*/
template <
typename T
>
void set_button_up_handler (
T& object,
void (T::*event_handler)(bool mouse_over, button& self)
);
/*!
requires
- event_handler is a valid pointer to a member function in T
ensures
- &self == this
- the event_handler function is called on object when the user causes
the button to go into its non-depressed state.
- if (the mouse is over this button when this event occurs) then
- mouse_over == true
- else
- mouse_over == false
- any previous calls to this function are overridden by this new call.
(i.e. you can only have one event handler associated with this
event at a time)
throws
- std::bad_alloc
!*/
void set_sourced_button_up_handler (
const any_function<void(bool mouse_over, button& self)>& event_handler
);
/*!
ensures
- &self == this
- the event_handler function is called when the user causes the
button to go into its non-depressed state.
- if (the mouse is over this button when this event occurs) then
- mouse_over == true
- else
- mouse_over == false
- any previous calls to this function are overridden by this new call.
(i.e. you can only have one event handler associated with this
event at a time)
throws
- std::bad_alloc
!*/
private:
// restricted functions
button(button&); // copy constructor
button& operator=(button&); // assignment operator
};
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
// class scroll_bar
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
class scroll_bar : public drawable
{
/*!
INITIAL VALUE
orientation() == a value given to the constructor.
max_slider_pos() == 0
slider_pos() == 0
jump_size() == 10
WHAT THIS OBJECT REPRESENTS
This object represents a scroll bar. The slider_pos() of the scroll bar
ranges from 0 to max_slider_pos(). The 0 position of the scroll_bar is
in the top or left side of the scroll_bar depending on its orientation.
When this object is disabled it means it will not respond to user clicks.
!*/
public:
enum bar_orientation
{
HORIZONTAL,
VERTICAL
};
scroll_bar(
drawable_window& w,
bar_orientation orientation
);
/*!
ensures
- #*this is properly initialized
- #*this has been added to window w
- #orientation() == orientation
- #parent_window() == w
throws
- std::bad_alloc
- dlib::thread_error
!*/
virtual ~scroll_bar(
);
/*!
ensures
- all resources associated with *this have been released
!*/
bar_orientation orientation (
) const;
/*!
ensures
- returns the orientation of this scroll_bar
!*/
template <
typename style_type
>
void set_style (
const style_type& style
);
/*!
requires
- style_type == a type that inherits from scroll_bar_style
ensures
- this scroll_bar object will draw itself using the given
scroll bar style
!*/
void set_length (
unsigned long length,
);
/*!
ensures
- if (orientation() == HORIZONTAL) then
- #width() == max(length,1)
- else
- #height() == max(length,1)
!*/
long max_slider_pos (
) const;
/*!
ensures
- returns the maximum value that slider_pos() can take.
!*/
void set_max_slider_pos (
long mpos
);
/*!
ensures
- if (mpos < 0) then
- #max_slider_pos() == 0
- else
- #max_slider_pos() == mpos
- if (slider_pos() > #max_slider_pos()) then
- #slider_pos() == #max_slider_pos()
- else
- #slider_pos() == slider_pos()
!*/
void set_slider_pos (
unsigned long pos
);
/*!
ensures
- if (pos < 0) then
- #slider_pos() == 0
- else if (pos > max_slider_pos()) then
- #slider_pos() == max_slider_pos()
- else
- #slider_pos() == pos
!*/
long slider_pos (
) const;
/*!
ensures
- returns the current position of the slider box within the scroll bar.
!*/
long jump_size (
) const;
/*!
ensures
- returns the number of positions that the slider bar will jump when the
user clicks on the empty gaps above or below the slider bar.
(note that the slider will jump less than the jump size if it hits the
end of the scroll bar)
!*/
void set_jump_size (
long js
);
/*!
ensures
- if (js < 1) then
- #jump_size() == 1
- else
- #jump_size() == js
!*/
template <
typename T
>
void set_scroll_handler (
T& object,
void (T::*event_handler)()
);
/*!
requires
- event_handler is a valid pointer to a member function in T
ensures
- The event_handler function is called whenever the user causes the slider box
to move.
- This event is NOT triggered by calling set_slider_pos()
- any previous calls to this function are overridden by this new call.
(i.e. you can only have one event handler associated with this
event at a time)
throws
- std::bad_alloc
!*/
void set_scroll_handler (
const any_function<void()>& event_handler
);
/*!
ensures
- The event_handler function is called whenever the user causes the slider box
to move.
- This event is NOT triggered by calling set_slider_pos()
- any previous calls to this function are overridden by this new call.
(i.e. you can only have one event handler associated with this
event at a time)
throws
- std::bad_alloc
!*/
private:
// restricted functions
scroll_bar(scroll_bar&); // copy constructor
scroll_bar& operator=(scroll_bar&); // assignment operator
};
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
// class widget_group
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
class widget_group : public drawable
{
/*!
INITIAL VALUE
size() == 0
get_rect().is_empty() == true
left() == 0
top() == 0
WHAT THIS OBJECT REPRESENTS
This object represents a grouping of drawable widgets. It doesn't draw
anything itself, rather it lets you manipulate the position, enabled
status, and visibility of a set of widgets as a group.
!*/
public:
widget_group(
drawable_window& w
);
/*!
ensures
- #*this is properly initialized
- #*this has been added to window w
- #parent_window() == w
throws
- std::bad_alloc
- dlib::thread_error
!*/
virtual ~widget_group(
);
/*!
ensures
- all resources associated with *this have been released.
!*/
void empty (
);
/*!
ensures
- #size() == 0
!*/
void fit_to_contents (
);
/*!
ensures
- does not change the position of this object.
(i.e. the upper left corner of get_rect() remains at the same position)
- if (size() == 0) then
- #get_rect().is_empty() == true
- else
- recursively calls fit_to_contents() on any widget_groups inside
this object.
- #get_rect() will be the smallest rectangle that contains all the
widgets in this group and the upper left corner of get_rect().
!*/
unsigned long size (
) const;
/*!
ensures
- returns the number of widgets currently in *this.
!*/
void add (
drawable& widget,
unsigned long x,
unsigned long y
);
/*!
ensures
- #is_member(widget) == true
- if (is_member(widget) == false) then
- #size() == size() + 1
- else
- #size() == size()
- The following conditions apply to this function as well as to all of the
following functions so long as is_member(widget) == true:
enable(), disable(), hide(), show(), set_z_order(), and set_pos().
- #widget.left() == left()+x
- #widget.width() == widget.width()
- #widget.top() == top()+y
- #widget.height() == widget.height()
- #widget.is_hidden() == is_hidden()
- #widget.is_enabled() == is_enabled()
- #widget.z_order() == z_order()
throws
- std::bad_alloc
!*/
bool is_member (
const drawable& widget
) const;
/*!
ensures
- returns true if widget is currently in this object, returns false otherwise.
!*/
void remove (
const drawable& widget
);
/*!
ensures
- #is_member(widget) == false
- if (is_member(widget) == true) then
- #size() == size() - 1
- else
- #size() == size()
!*/
protected:
// this object doesn't draw anything but also isn't abstract
void draw (
const canvas& c
) const {}
private:
// restricted functions
widget_group(widget_group&); // copy constructor
widget_group& operator=(widget_group&); // assignment operator
};
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
// class image_widget
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
class image_widget : public draggable
{
/*!
INITIAL VALUE
draggable_area() == an initial value for its type.
This object isn't displaying anything.
WHAT THIS OBJECT REPRESENTS
This object represents a draggable image. You give it an image to display
by calling set_image().
Also note that initially the draggable area is empty so it won't be
draggable unless you call set_draggable_area() to some non-empty region.
The image is drawn such that:
- the pixel img[0][0] is the upper left corner of the image.
- the pixel img[img.nr()-1][0] is the lower left corner of the image.
- the pixel img[0][img.nc()-1] is the upper right corner of the image.
- the pixel img[img.nr()-1][img.nc()-1] is the lower right corner of the image.
!*/
public:
image_widget(
drawable_window& w
);
/*!
ensures
- #*this is properly initialized
- #*this has been added to window w
- #parent_window() == w
throws
- std::bad_alloc
- dlib::thread_error
!*/
virtual ~image_widget(
);
/*!
ensures
- all resources associated with *this have been released
!*/
template <
typename image_type
>
void set_image (
const image_type& img
);
/*!
requires
- image_type == an implementation of array2d/array2d_kernel_abstract.h
- pixel_traits<typename image_type::type> must be defined
ensures
- #width() == img.nc()
- #height() == img.nr()
- #*this widget is now displaying the given image img.
!*/
private:
// restricted functions
image_widget(image_widget&); // copy constructor
image_widget& operator=(image_widget&); // assignment operator
};
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
// class tooltip
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
class tooltip : public mouse_over_event
{
/*!
INITIAL VALUE
- text() == ""
- the tooltip is inactive until the text is changed to
a non-empty string.
WHAT THIS OBJECT REPRESENTS
This object represents a region on a window where if the user
hovers the mouse over this region a tooltip with a message
appears.
!*/
public:
tooltip(
drawable_window& w
);
/*!
ensures
- #*this is properly initialized
- #*this has been added to window w
- #parent_window() == w
throws
- std::bad_alloc
- dlib::thread_error
!*/
virtual ~tooltip(
);
/*!
ensures
- all resources associated with *this have been released
!*/
void set_size (
unsigned long width_,
unsigned long height_
);
/*!
ensures
- #width() == width_
- #height() == height_
- #top() == top()
- #left() == left()
- i.e. The location of the upper left corner of this widget stays the
same but its width and height are modified
!*/
void set_text (const std::wstring& str);
void set_text (const dlib::ustring& str);
void set_text (
const std::string& str
);
/*!
ensures
- #text() == str
- activates the tooltip. i.e. after this function the tooltip
will display on the screen when the user hovers the mouse over it
!*/
const std::wstring wtext () const;
const dlib::ustring utext () const;
const std::string text (
) const;
/*!
ensures
- returns the text that is displayed inside this
tooltip
!*/
private:
// restricted functions
tooltip(tooltip&); // copy constructor
tooltip& operator=(tooltip&); // assignment operator
};
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
// popup menu stuff
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
class menu_item
{
/*!
WHAT THIS OBJECT REPRESENTS
This is an abstract class that defines the interface a
menu item in a popup_menu must implement.
Note that a menu_item is drawn as 3 separate pieces:
---------------------------------
| left | middle | right |
---------------------------------
Also note that derived classes must be copyable via
their copy constructors.
!*/
public:
virtual ~menu_item() {}
virtual void on_click (
) const {}
/*!
requires
- the mutex drawable::m is locked
- if (has_click_event()) then
- this function is called when the user clicks on this menu_item
!*/
virtual bool has_click_event (
) const { return false; }
/*!
ensures
- if (this menu_item wants to receive on_click events) then
- returns true
- else
- returns false
!*/
virtual unichar get_hot_key (
) const { return 0; }
/*!
ensures
- if (this menu item has a keyboard hot key) then
- returns the unicode value of the key
- else
- returns 0
!*/
virtual rectangle get_left_size (
) const { return rectangle(); } // return empty rect by default
/*!
ensures
- returns the dimensions of the left part of the menu_item
!*/
virtual rectangle get_middle_size (
) const = 0;
/*!
ensures
- returns the dimensions of the middle part of the menu_item
!*/
virtual rectangle get_right_size (
) const { return rectangle(); } // return empty rect by default
/*!
ensures
- returns the dimensions of the right part of the menu_item
!*/
virtual void draw_background (
const canvas& c,
const rectangle& rect,
const bool enabled,
const bool is_selected
) const {}
/*!
requires
- the mutex drawable::m is locked
requires
- c == the canvas to draw on
- rect == the rectangle in which we are to draw the background
- enabled == true if the menu_item is to be drawn enabled
- is_selected == true if the menu_item is to be drawn selected
ensures
- draws the background of the menu_item on the canvas c at the location
given by rect.
!*/
virtual void draw_left (
const canvas& c,
const rectangle& rect,
const bool enabled,
const bool is_selected
) const {}
/*!
requires
- the mutex drawable::m is locked
requires
- c == the canvas to draw on
- rect == the rectangle in which we are to draw the background
- enabled == true if the menu_item is to be drawn enabled
- is_selected == true if the menu_item is to be drawn selected
ensures
- draws the left part of the menu_item on the canvas c at the location
given by rect.
!*/
virtual void draw_middle (
const canvas& c,
const rectangle& rect,
const bool enabled,
const bool is_selected
) const = 0;
/*!
requires
- the mutex drawable::m is locked
requires
- c == the canvas to draw on
- rect == the rectangle in which we are to draw the background
- enabled == true if the menu_item is to be drawn enabled
- is_selected == true if the menu_item is to be drawn selected
ensures
- draws the middle part of the menu_item on the canvas c at the location
given by rect.
!*/
virtual void draw_right (
const canvas& c,
const rectangle& rect,
const bool enabled,
const bool is_selected
) const {}
/*!
requires
- the mutex drawable::m is locked
requires
- c == the canvas to draw on
- rect == the rectangle in which we are to draw the background
- enabled == true if the menu_item is to be drawn enabled
- is_selected == true if the menu_item is to be drawn selected
ensures
- draws the right part of the menu_item on the canvas c at the location
given by rect.
!*/
};
// ----------------------------------------------------------------------------------------
class menu_item_text : public menu_item
{
/*!
WHAT THIS OBJECT REPRESENTS
This object is a simple text menu item
!*/
public:
template <
typename T
>
menu_item_text (
const std::string& str,
T& object,
void (T::*on_click_handler)(),
unichar hotkey = 0
);
/*!
ensures
- The text of this menu item will be str
- the on_click_handler function is called on object when this menu_item
clicked by the user.
- #get_hot_key() == hotkey
!*/
menu_item_text (
const std::string& str,
const any_function<void()>& on_click_handler,
unichar hotkey = 0
);
/*!
ensures
- The text of this menu item will be str
- the on_click_handler function is called when this menu_item
clicked by the user.
- #get_hot_key() == hotkey
!*/
// overloads for wide character strings
template <
typename T
>
menu_item_text (
const std::wstring& str,
T& object,
void (T::*on_click_handler)(),
unichar hotkey = 0
);
menu_item_text (
const std::wstring& str,
const any_function<void()>& on_click_handler,
unichar hotkey = 0
);
template <
typename T
>
menu_item_text (
const dlib::ustring& str,
T& object,
void (T::*on_click_handler)(),
unichar hotkey = 0
);
template <
typename T
>
menu_item_text (
const dlib::ustring& str,
const any_function<void()>& on_click_handler,
unichar hotkey = 0
);
};
// ----------------------------------------------------------------------------------------
class menu_item_submenu : public menu_item
{
/*!
WHAT THIS OBJECT REPRESENTS
This object is a simple text item intended to be used with
submenus inside a popup_menu.
!*/
public:
menu_item_submenu (
const std::string& str,
unichar hotkey = 0
);
/*!
ensures
- The text of this menu item will be str
- #get_hot_key() == hotkey
!*/
//overloads for wide character strings
menu_item_submenu (
const std::wstring& str,
unichar hotkey = 0
);
menu_item_submenu (
const dlib::ustring& str,
unichar hotkey = 0
);
};
// ----------------------------------------------------------------------------------------
class menu_item_separator : public menu_item
{
/*!
WHAT THIS OBJECT REPRESENTS
This object is a horizontal separator in a popup menu
!*/
};
// ----------------------------------------------------------------------------------------
class popup_menu : public base_window
{
/*!
INITIAL VALUE
- size() == 0
WHAT THIS OBJECT REPRESENTS
This object represents a popup menu window capable of containing
menu_item objects.
!*/
public:
popup_menu (
);
/*!
ensures
- #*this is properly initialized
throws
- std::bad_alloc
- dlib::thread_error
- dlib::gui_error
!*/
void clear (
);
/*!
ensures
- #*this has its initial value
throws
- std::bad_alloc
if this exception is thrown then *this is unusable
until clear() is called and succeeds
!*/
template <
typename menu_item_type
>
unsigned long add_menu_item (
const menu_item_type& new_item
);
/*!
requires
- menu_item_type == a type that inherits from menu_item
ensures
- adds new_item onto the bottom of this popup_menu.
- returns size()
(This is also the index by which this item can be
referenced by the enable_menu_item() and disable_menu_item()
functions.)
!*/
template <
typename menu_item_type
>
unsigned long add_submenu (
const menu_item_type& new_item,
popup_menu& submenu
);
/*!
requires
- menu_item_type == a type that inherits from menu_item
ensures
- adds new_item onto the bottom of this popup_menu.
- when the user puts the mouse above this menu_item the given
submenu popup_menu will be displayed.
- returns size()
(This is also the index by which this item can be
referenced by the enable_menu_item() and disable_menu_item()
functions.)
!*/
void enable_menu_item (
unsigned long idx
);
/*!
requires
- idx < size()
ensures
- the menu_item in this with the index idx has been enabled
!*/
void disable_menu_item (
unsigned long idx
);
/*!
requires
- idx < size()
ensures
- the menu_item in this with the index idx has been disabled
!*/
unsigned long size (
) const;
/*!
ensures
- returns the number of menu_item objects in this popup_menu
!*/
template <typename T>
void set_on_hide_handler (
T& object,
void (T::*event_handler)()
);
/*!
ensures
- the event_handler function is called on object when this popup_menu
hides itself due to an action by the user.
- Note that you can register multiple handlers for this event.
!*/
void select_first_item (
);
/*!
ensures
- causes this popup menu to highlight the first
menu item that it contains which has a click event
and is enabled.
!*/
bool forwarded_on_keydown (
unsigned long key,
bool is_printable,
unsigned long state
);
/*!
requires
- key, is_printable, and state are the variables from the
base_window::on_keydown() event
ensures
- forwards this keyboard event to this popup window so that it
may deal with keyboard events from other windows.
- if (this popup_menu uses the keyboard event) then
- returns true
- else
- returns false
!*/
private:
// restricted functions
popup_menu(popup_menu&); // copy constructor
popup_menu& operator=(popup_menu&); // assignment operator
};
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
// class popup_menu_region
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
class popup_menu_region : public drawable
{
/*!
INITIAL VALUE
- popup_menu_visible() == false
WHAT THIS OBJECT REPRESENTS
This object represents a region on a window where if the user
right clicks the mouse over this region a popup_menu pops up.
Note that this widget doesn't actually draw anything, it just
provides a region the user can click on to get a popup menu.
!*/
public:
popup_menu_region(
drawable_window& w
);
/*!
ensures
- #*this is properly initialized
- #*this has been added to window w
- #parent_window() == w
throws
- std::bad_alloc
- dlib::thread_error
!*/
virtual ~popup_menu_region(
);
/*!
ensures
- all resources associated with *this have been released
!*/
void set_size (
unsigned long width_,
unsigned long height_
);
/*!
ensures
- #width() == width_
- #height() == height_
- #top() == top()
- #left() == left()
- i.e. The location of the upper left corner of this widget stays the
same but its width and height are modified
!*/
void set_rect (
const rectangle& new_rect
);
/*!
ensures
- #get_rect() == new_rect
!*/
bool popup_menu_visible (
) const;
/*!
ensures
- if (the popup menu is currently visible on the screen) then
- returns true
- else
- returns false
!*/
popup_menu& menu (
);
/*!
ensures
- returns a reference to the popup_menu for this object. It is
the menu that is displayed when the user right clicks on
this widget
!*/
private:
// restricted functions
popup_menu_region(popup_menu_region&); // copy constructor
popup_menu_region& operator=(popup_menu_region&); // assignment operator
};
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
// class zoomable_region
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
class zoomable_region : public drawable
{
/*
INITIAL VALUE
- min_zoom_scale() == 0.15
- max_zoom_scale() == 1.0
- zoom_increment() == 0.90
- zoom_scale() == 1.0
WHAT THIS OBJECT REPRESENTS
This object represents a 2D Cartesian graph that you can zoom into and
out of. It is a graphical widget that draws a rectangle with
a horizontal and vertical scroll bar that allow the user to scroll
around on a Cartesian graph that is much larger than the actual
area occupied by this object on the screen. It also allows
the user to zoom in and out.
To use this object you inherit from it and make use of its public and
protected member functions. It provides functions for converting between
pixel locations and the points in our 2D Cartesian graph so that when the
user is scrolling/zooming the widget you can still determine where
things are to be placed on the screen and what screen pixels correspond
to in the Cartesian graph.
Note that the Cartesian graph in this object is bounded by the point
(0,0), corresponding to the upper left corner when we are zoomed all
the way out, and max_graph_point() which corresponds to the lower right
corner when zoomed all the way out. The value of max_graph_point() is
determined automatically from the size of this object's on screen
rectangle and the value of min_zoom_scale() which determines how far
out you can zoom.
*/
public:
zoomable_region (
drawable_window& w,
unsigned long events = 0
);
/*!
ensures
- #*this is properly initialized
- #*this has been added to window w
- #parent_window() == w
- This object will not receive any events or draw() requests until
enable_events() is called
- the events flags are passed on to the drawable object's
constructor.
throws
- std::bad_alloc
- dlib::thread_error
!*/
virtual ~zoomable_region (
) = 0;
/*!
ensures
- all resources associated with *this have been released
!*/
template <
typename style_type
>
void set_style (
const style_type& style_
);
/*!
requires
- style_type == a type that inherits from scrollable_region_style
ensures
- this zoomable_region object will draw itself using the given
style
!*/
void set_zoom_increment (
double zi
);
/*!
requires
- 0 < zi < 1
ensures
- #zoom_increment() == zi
!*/
double zoom_increment (
) const;
/*!
ensures
- When the user zooms in using the mouse wheel:
- #zoom_scale() == zoom_scale() / zoom_increment()
- When the user zooms out using the mouse wheel:
- #zoom_scale() == zoom_scale() * zoom_increment()
- So this function returns the number that determines how much the zoom
changes when the mouse wheel is moved.
!*/
void set_max_zoom_scale (
double ms
);
/*!
requires
- ms > 0
ensures
- #max_zoom_scale() == ms
!*/
void set_min_zoom_scale (
double ms
);
/*!
requires
- ms > 0
ensures
- #min_zoom_scale() == ms
!*/
double min_zoom_scale (
) const;
/*!
ensures
- returns the minimum allowed value of zoom_scale()
(i.e. this is the number that determines how far out the user is allowed to zoom)
!*/
double max_zoom_scale (
) const;
/*!
ensures
- returns the maximum allowed value of zoom_scale()
(i.e. this is the number that determines how far in the user is allowed to zoom)
!*/
virtual void set_size (
unsigned long width,
unsigned long height
);
/*!
ensures
- #width() == width_
- #height() == height_
- #top() == top()
- #left() == left()
- i.e. The location of the upper left corner of this button stays the
same but its width and height are modified
!*/
protected:
rectangle display_rect (
) const;
/*!
requires
- mutex drawable::m is locked
ensures
- returns the rectangle on the screen that contains the Cartesian
graph in this widget. I.e. this is the area of this widget minus
the area taken up by the scroll bars and border decorations.
!*/
point graph_to_gui_space (
const vector<double,2>& graph_point
) const;
/*!
requires
- mutex drawable::m is locked
ensures
- returns the location of the pixel on the screen that corresponds
to the given point in Cartesian graph space
!*/
vector<double,2> gui_to_graph_space (
const point& pixel_point
) const;
/*!
requires
- mutex drawable::m is locked
ensures
- returns the point in Cartesian graph space that corresponds to the given
pixel location
!*/
vector<double,2> max_graph_point (
) const;
/*!
requires
- mutex drawable::m is locked
ensures
- returns the pixel farthest from the graph point (0,0) that is still
in the graph. I.e. returns the point in graph space that corresponds
to the lower right corner of the display_rect() when we are zoomed
all the way out.
!*/
double zoom_scale (
) const;
/*!
requires
- mutex drawable::m is locked
ensures
- returns a double Z that represents the current zoom.
- Smaller values of Z represent the user zooming out.
- Bigger values of Z represent the user zooming in.
- The default unzoomed case is when Z == 1
- objects should be drawn such that they are zoom_scale()
times their normal size
!*/
void set_zoom_scale (
double new_scale
);
/*!
requires
- mutex drawable::m is locked
ensures
- invalidates the display_rect() so that it will be redrawn
- if (min_zoom_scale() <= new_scale && new_scale <= max_zoom_scale()) then
- #zoom_scale() == new_scale
- else if (new_scale < min_zoom_scale()) then
- #zoom_scale() == min_zoom_scale()
- else if (new_scale > max_zoom_scale()) then
- #zoom_scale() == max_zoom_scale()
!*/
void center_display_at_graph_point (
const vector<double,2>& graph_point
);
/*!
requires
- mutex drawable::m is locked
ensures
- causes the given graph point to be centered in the display
if possible
- invalidates the display_rect() so that it will be redrawn
!*/
virtual void on_view_changed (
) {}
/*!
requires
- events_are_enabled() == true
- mutex drawable::m is locked
ensures
- on_view_changed() is called whenever the user causes the view of the
zoomable_region to change. That is, this function is called when the
user scrolls or zooms around in the region.
!*/
// ---------------------------- event handlers ----------------------------
// The following event handlers are used in this object. So if you
// use any of them in your derived object you should pass the events
// back to it so that they still operate unless you wish to hijack the
// event for your own reasons (e.g. to override the mouse drag this object
// performs)
void on_wheel_down (unsigned long state);
void on_wheel_up (unsigned long state);
void on_mouse_move ( unsigned long state, long x, long y);
void on_mouse_up ( unsigned long btn, unsigned long state, long x, long y);
void on_mouse_down ( unsigned long btn, unsigned long state, long x, long y, bool is_double_click);
void draw ( const canvas& c) const;
private:
// restricted functions
zoomable_region(zoomable_region&); // copy constructor
zoomable_region& operator=(zoomable_region&); // assignment operator
};
// ----------------------------------------------------------------------------------------
class scrollable_region : public drawable
{
/*!
INITIAL VALUE
- horizontal_scroll_pos() == 0
- horizontal_scroll_increment() == 1
- horizontal_mouse_wheel_scroll_increment() == 1
- vertical_scroll_pos() == 0
- vertical_scroll_increment() == 1
- vertical_mouse_wheel_scroll_increment() == 1
- total_rect().empty() == true
- mouse_drag_enabled() == false
WHAT THIS OBJECT REPRESENTS
This object represents a 2D region of arbitrary size that is displayed
within a possibly smaller scrollable gui widget. That is, it is a
graphical widget that draws a rectangle with a horizontal and vertical
scroll bar that allows the user to scroll around on a region that is much
larger than the actual area occupied by this object on the screen.
To use this object you inherit from it and make use of its public and
protected member functions. It provides a function, total_rect(), that
tells you where the 2D region is on the screen. You draw your stuff
inside total_rect() as you would normally except that you only modify
pixels that are also inside display_rect(). When the user moves the
scroll bars the position of total_rect() is updated accordingly, causing
the widget's content to scroll across the screen.
!*/
public:
scrollable_region (
drawable_window& w,
unsigned long events = 0
);
/*!
ensures
- #*this is properly initialized
- #*this has been added to window w
- #parent_window() == w
- This object will not receive any events or draw() requests until
enable_events() is called
- the events flags are passed on to the drawable object's
constructor.
throws
- std::bad_alloc
- dlib::thread_error
!*/
virtual ~scrollable_region (
) = 0;
/*!
ensures
- all resources associated with *this have been released
!*/
template <
typename style_type
>
void set_style (
const style_type& style_
);
/*!
requires
- style_type == a type that inherits from scrollable_region_style
ensures
- this scrollable_region object will draw itself using the given
style
!*/
virtual void set_size (
unsigned long width,
unsigned long height
);
/*!
ensures
- #width() == width_
- #height() == height_
- #top() == top()
- #left() == left()
- i.e. The location of the upper left corner of this widget stays the
same but its width and height are modified.
!*/
long horizontal_scroll_pos (
) const;
/*!
ensures
- returns the current position of the horizontal scroll bar.
0 means it is at the far left while bigger values represent
scroll positions closer to the right.
!*/
long vertical_scroll_pos (
) const;
/*!
ensures
- returns the current position of the vertical scroll bar.
0 means it is at the top and bigger values represent scroll positions
closer to the bottom.
!*/
void set_horizontal_scroll_pos (
long pos
);
/*!
ensures
- if (pos is a valid horizontal scroll position) then
- #horizontal_scroll_pos() == pos
- else
- #horizontal_scroll_pos() == the valid scroll position closest to pos
!*/
void set_vertical_scroll_pos (
long pos
);
/*!
ensures
- if (pos is a valid vertical scroll position) then
- #vertical_scroll_pos() == pos
- else
- #vertical_scroll_pos() == the valid scroll position closest to pos
!*/
unsigned long horizontal_mouse_wheel_scroll_increment (
) const;
/*!
ensures
- returns the number of positions the horizontal scroll bar
moves when the user scrolls the mouse wheel.
!*/
unsigned long vertical_mouse_wheel_scroll_increment (
) const;
/*!
ensures
- returns the number of positions the vertical scroll bar
moves when the user scrolls the mouse wheel.
!*/
void set_horizontal_mouse_wheel_scroll_increment (
unsigned long inc
);
/*!
ensures
- #horizontal_mouse_wheel_scroll_increment() == inc
!*/
void set_vertical_mouse_wheel_scroll_increment (
unsigned long inc
);
/*!
ensures
- #vertical_mouse_wheel_scroll_increment() == inc
!*/
unsigned long horizontal_scroll_increment (
) const;
/*!
ensures
- returns the number of pixels that total_rect() is moved by when
the horizontal scroll bar moves by one position
!*/
unsigned long vertical_scroll_increment (
) const;
/*!
ensures
- returns the number of pixels that total_rect() is moved by when
the vertical scroll bar moves by one position
!*/
void set_horizontal_scroll_increment (
unsigned long inc
);
/*!
ensures
- #horizontal_scroll_increment() == inc
!*/
void set_vertical_scroll_increment (
unsigned long inc
);
/*!
ensures
- #vertical_scroll_increment() == inc
!*/
bool mouse_drag_enabled (
) const;
/*!
ensures
- if (the user can drag this contents of this widget around by
holding down the left mouse button and dragging) then
- returns true
- else
- returns false
!*/
void enable_mouse_drag (
);
/*!
ensures
- #mouse_drag_enabled() == true
!*/
void disable_mouse_drag (
);
/*!
ensures
- #mouse_drag_enabled() == false
!*/
protected:
rectangle display_rect (
) const;
/*!
requires
- mutex drawable::m is locked
ensures
- returns the rectangle on the screen that contains the scrollable
area in this widget. I.e. this is the area of this widget minus
the area taken up by the scroll bars and border decorations.
!*/
void set_total_rect_size (
unsigned long width,
unsigned long height
);
/*!
requires
- mutex drawable::m is locked
- (width > 0 && height > 0) || (width == 0 && height == 0)
ensures
- #total_rect().width() == width
- #total_rect().height() == height
- The scroll bars as well as the position of #total_rect()
is updated so that the total rect is still in the correct
position with respect to the scroll bars.
!*/
const rectangle& total_rect (
) const;
/*!
requires
- mutex drawable::m is locked
ensures
- returns a rectangle that represents the entire scrollable
region inside this widget, even the parts that are outside
display_rect().
!*/
void scroll_to_rect (
const rectangle& r
);
/*!
requires
- mutex drawable::m is locked
ensures
- Adjusts the scroll bars of this object so that the part of
the total_rect() rectangle that overlaps with r is displayed in
the display_rect() rectangle on the screen.
!*/
virtual void on_view_changed (
) {}
/*!
requires
- events_are_enabled() == true
- mutex drawable::m is locked
ensures
- on_view_changed() is called whenever the user causes the view of the
scrollable_region to change. That is, this function is called when the
user scrolls around in the region.
!*/
// ---------------------------- event handlers ----------------------------
// The following event handlers are used in this object. So if you
// use any of them in your derived object you should pass the events
// back to it so that they still operate unless you wish to hijack the
// event for your own reasons (e.g. to override the mouse wheel action
// this object performs)
void on_wheel_down (unsigned long state);
void on_wheel_up (unsigned long state);
void on_mouse_move (unsigned long state, long x, long y);
void on_mouse_down (unsigned long btn, unsigned long state, long x, long y, bool is_double_click);
void on_mouse_up (unsigned long btn, unsigned long state, long x, long y);
void draw (const canvas& c) const;
private:
// restricted functions
scrollable_region(scrollable_region&); // copy constructor
scrollable_region& operator=(scrollable_region&); // assignment operator
};
// ----------------------------------------------------------------------------------------
}
#endif // DLIB_BASE_WIDGETs_ABSTRACT_