view.h
1 /*
2 ** ClanLib SDK
3 ** Copyright (c) 1997-2016 The ClanLib Team
4 **
5 ** This software is provided 'as-is', without any express or implied
6 ** warranty. In no event will the authors be held liable for any damages
7 ** arising from the use of this software.
8 **
9 ** Permission is granted to anyone to use this software for any purpose,
10 ** including commercial applications, and to alter it and redistribute it
11 ** freely, subject to the following restrictions:
12 **
13 ** 1. The origin of this software must not be misrepresented; you must not
14 ** claim that you wrote the original software. If you use this software
15 ** in a product, an acknowledgment in the product documentation would be
16 ** appreciated but is not required.
17 ** 2. Altered source versions must be plainly marked as such, and must not be
18 ** misrepresented as being the original software.
19 ** 3. This notice may not be removed or altered from any source distribution.
20 **
21 ** Note: Some of the libraries ClanLib may link to may have additional
22 ** requirements or restrictions.
23 **
24 ** File Author(s):
25 **
26 ** Magnus Norddahl
27 ** Artem Khomenko (Direct redraw changed state of View, without redraw the entire window).
28 */
29 
30 #pragma once
31 
32 #include "../../Core/Math/mat4.h"
33 #include "../../Core/Math/rect.h"
34 #include "../../Core/Math/easing.h"
35 #include "../../Core/Signals/signal.h"
36 #include "../../UI/Events/event.h"
37 #include "../View/view_geometry.h"
38 #include "../Style/style.h"
39 #include "../Style/style_cascade.h"
40 #include "../Style/style_get_value.h"
41 #include "focus_policy.h"
42 #include <vector>
43 #include <memory>
44 #include <functional>
45 
46 namespace clan
47 {
48  class Style;
49  class StyleCascade;
50  class Canvas;
51  class ActivationChangeEvent;
52  class CloseEvent;
53  class FocusChangeEvent;
54  class PointerEvent;
55  class ResizeEvent;
56  class KeyEvent;
57  class ViewImpl;
58  class CursorDescription;
59  enum class StandardCursor;
60  class DisplayWindow;
61  class ViewTree;
62  class ViewAction;
63 
65  class View : public std::enable_shared_from_this<View>
66  {
67  public:
68  View();
69  virtual ~View();
70 
72  const StyleCascade &style_cascade() const;
73 
75  const std::shared_ptr<Style> &style(const std::string &state = std::string()) const;
76 
78  bool state(const std::string &name) const;
79 
81  void set_state(const std::string &name, bool value);
82 
84  void set_state_cascade(const std::string &name, bool value);
85 
88 
90  View *parent() const;
91 
93  const std::vector<std::shared_ptr<View>> &children() const;
94 
96  void add_child(const std::shared_ptr<View> &view);
97 
98  template<typename T, typename... Types>
99  std::shared_ptr<T> add_child(Types &&... args)
100  {
101  auto child = std::make_shared<T>(std::forward<Types>(args)...);
102  add_child(child);
103  return child;
104  }
105 
106  std::shared_ptr<View> add_child()
107  {
108  return add_child<View>();
109  }
110 
112  void remove_from_parent();
113 
115  void add_action(const std::shared_ptr<ViewAction> &action);
116 
117  template<typename T, typename... Types>
118  std::shared_ptr<T> add_action(Types &&... args)
119  {
120  auto action = std::make_shared<T>(std::forward<Types>(args)...);
121  add_action(action);
122  return action;
123  }
124 
126  const std::vector<std::shared_ptr<ViewAction>> &actions() const;
127 
129  bool hidden() const;
130 
132  void set_hidden(bool value = true);
133 
135  bool is_static_position_and_visible() const;
136 
138  bool needs_layout() const;
139 
141  void set_needs_layout();
142 
144  const ViewGeometry &geometry() const;
145 
149  void set_geometry(const ViewGeometry &geometry);
150 
154  Canvas canvas() const;
155 
157  void set_needs_render();
158 
160  bool render_exception_encountered() const;
161 
166 
168  const Mat4f &view_transform() const;
169 
171  void set_view_transform(const Mat4f &transform);
172 
174  bool content_clipped() const;
175 
177  void set_content_clipped(bool clipped);
178 
180  float preferred_width(Canvas &canvas);
181 
183  float preferred_height(Canvas &canvas, float width);
184 
186  float first_baseline_offset(Canvas &canvas, float width);
187 
189  float last_baseline_offset(Canvas &canvas, float width);
190 
192  virtual void layout_children(Canvas &canvas);
193 
195  const ViewTree *view_tree() const;
196  ViewTree *view_tree();
197 
199  View *focus_view() const;
200 
202  std::shared_ptr<View> find_view_at(const Pointf &pos) const;
203 
205  FocusPolicy focus_policy() const;
206 
208  void set_focus_policy(FocusPolicy policy);
209 
211  unsigned int tab_index() const;
212 
214  void set_tab_index(unsigned int index);
215 
217  void set_focus();
218 
220  void remove_focus();
221 
223  bool has_focus() const { return focus_view() == this; }
224 
226  void prev_focus();
227 
229  void next_focus();
230 
232  void animate(float from, float to, const std::function<void(float)> &setter, int duration_ms = 400, const std::function<float(float)> &easing = Easing::linear, std::function<void()> animation_end = std::function<void()>());
233 
235  void stop_animations();
236 
238  void set_cursor(const CursorDescription &cursor);
239  void set_cursor(StandardCursor type);
240 
242  void set_inherit_cursor();
243 
245  Signal<void(ActivationChangeEvent &)> &sig_activated(bool use_capture = false);
246 
248  Signal<void(ActivationChangeEvent &)> &sig_deactivated(bool use_capture = false);
249 
251  Signal<void(CloseEvent &)> &sig_close(bool use_capture = false);
252 
254  Signal<void(ResizeEvent &)> &sig_resize(bool use_capture = false);
255 
257  Signal<void(FocusChangeEvent &)> &sig_focus_gained(bool use_capture = false);
258 
260  Signal<void(FocusChangeEvent &)> &sig_focus_lost(bool use_capture = false);
261 
263  Signal<void(PointerEvent &)> &sig_pointer_enter(bool use_capture = false);
264 
266  Signal<void(PointerEvent &)> &sig_pointer_leave(bool use_capture = false);
267 
269  Signal<void(PointerEvent &)> &sig_pointer_move(bool use_capture = false);
270 
272  Signal<void(PointerEvent &)> &sig_pointer_press(bool use_capture = false);
273 
275  Signal<void(PointerEvent &)> &sig_pointer_release(bool use_capture = false);
276 
278  Signal<void(PointerEvent &)> &sig_pointer_double_click(bool use_capture = false);
279 
282 
284  Signal<void(KeyEvent &)> &sig_key_press(bool use_capture = false);
285 
287  Signal<void(KeyEvent &)> &sig_key_release(bool use_capture = false);
288 
290  void update_cursor(DisplayWindow &window);
291 
293  Pointf to_screen_pos(const Pointf &pos);
294 
296  Pointf from_screen_pos(const Pointf &pos);
297 
299  Pointf to_root_pos(const Pointf &pos, bool relative_to_margin = false);
300 
302  Pointf from_root_pos(const Pointf &pos);
303 
305  static void dispatch_event(View *target, EventUI *e, bool no_propagation = false);
306 
308  void draw_without_layout();
309 
310  protected:
312  virtual void render_content(Canvas &canvas) { }
313 
315  virtual void render_border(Canvas &canvas);
316 
318  virtual void render_background(Canvas &canvas);
319 
321  virtual void child_added(const std::shared_ptr<View> &view) { }
322 
324  virtual void child_removed(const std::shared_ptr<View> &view) { }
325 
327  virtual float calculate_preferred_width(Canvas &canvas);
328 
330  virtual float calculate_preferred_height(Canvas &canvas, float width);
331 
333  virtual float calculate_first_baseline_offset(Canvas &canvas, float width);
334 
336  virtual float calculate_last_baseline_offset(Canvas &canvas, float width);
337 
338  private:
339  View(const View &) = delete;
340  View &operator=(const View &) = delete;
341 
342  std::unique_ptr<ViewImpl> impl;
343 
344  friend class ViewTree;
345  friend class ViewImpl;
346  friend class ViewAction;
347  };
348 }
static void dispatch_event(View *target, EventUI *e, bool no_propagation=false)
Dispatch event to signals listening for events.
virtual float calculate_preferred_width(Canvas &canvas)
Calculates the preferred width of this view.
const std::shared_ptr< Style > & style(const std::string &state=std::string()) const
Style properties for the specified state.
const std::vector< std::shared_ptr< ViewAction > > & actions() const
List of all action recognizers.
Definition: clanapp.h:35
View for an area of the user interface.
Definition: view.h:65
Signal< void(PointerEvent &)> & sig_pointer_proximity_change(bool use_capture=false)
Pointer proximity change event.
StandardCursor
Standard Cursor.
Definition: display_window.h:68
virtual void layout_children(Canvas &canvas)
Sets the view geometry for all children of this view.
C style comment block.
virtual float calculate_preferred_height(Canvas &canvas, float width)
Calculates the preferred height of this view.
View * parent() const
Parent view node or nullptr if the view is the current root node.
Pointf from_root_pos(const Pointf &pos)
Map from root content to local content coordinates.
Signal< void(FocusChangeEvent &)> & sig_focus_lost(bool use_capture=false)
View lost focus event.
Pointf to_screen_pos(const Pointf &pos)
Map from local content to screen coordinates.
2D Graphics Canvas
Definition: canvas.h:71
void set_focus_policy(FocusPolicy policy)
Set if this view automatically can gain focus.
Definition: view_geometry.h:38
void add_action(const std::shared_ptr< ViewAction > &action)
Add an action recognizer.
Signal< void(ActivationChangeEvent &)> & sig_activated(bool use_capture=false)
Window activated event.
float preferred_height(Canvas &canvas, float width)
Calculates the preferred height of this view.
virtual ~View()
Signal< void(KeyEvent &)> & sig_key_press(bool use_capture=false)
Key pressed event.
void remove_focus()
Remove focus from this view.
void next_focus()
Give focus to the next view in the keyboard tab index order.
virtual void render_background(Canvas &canvas)
Renders the background of a view.
Signal< void(PointerEvent &)> & sig_pointer_double_click(bool use_capture=false)
Pointer button double clicked event.
friend class ViewImpl
Definition: view.h:345
View * focus_view() const
The view receiving keyboard events or nullptr if no view has the focus.
unsigned int tab_index() const
Tab index for keyboard focus changes.
Signal< void(CloseEvent &)> & sig_close(bool use_capture=false)
Window close button clicked event.
const std::vector< std::shared_ptr< View > > & children() const
List of all immediate child views.
void set_view_transform(const Mat4f &transform)
Specifies the view transform to be applied before its contents and children are rendered.
FocusPolicy focus_policy() const
Focus policy active for this view.
Signal< void(ActivationChangeEvent &)> & sig_deactivated(bool use_capture=false)
Window deactivated event.
bool has_focus() const
Test if this view is receiving keyboard input.
Definition: view.h:223
void clear_exception_encountered()
bool render_exception_encountered() const
Test if this view generated an exception during rendering.
virtual void child_removed(const std::shared_ptr< View > &view)
Child view was removed from this view.
Definition: view.h:324
static float linear(float t)
Signal< void(PointerEvent &)> & sig_pointer_leave(bool use_capture=false)
Pointer leaving view geometry event.
float first_baseline_offset(Canvas &canvas, float width)
Calculates the offset to the first baseline.
Signal< void(PointerEvent &)> & sig_pointer_press(bool use_capture=false)
Pointer button pressed event.
virtual float calculate_first_baseline_offset(Canvas &canvas, float width)
Calculates the offset to the first baseline.
void remove_from_parent()
Remove view from parent.
void animate(float from, float to, const std::function< void(float)> &setter, int duration_ms=400, const std::function< float(float)> &easing=Easing::linear, std::function< void()> animation_end=std::function< void()>())
Continously call an animation function for the specified duration.
void set_content_clipped(bool clipped)
Specifies if content should be clipped during rendering.
Base class for events being dispatched through the view hiarchy.
Definition: UI/Events/event.h:47
4D matrix
Definition: mat2.h:50
Signal< void(KeyEvent &)> & sig_key_release(bool use_capture=false)
Key released event.
virtual float calculate_last_baseline_offset(Canvas &canvas, float width)
Calculates the offset to the last baseline.
virtual void render_content(Canvas &canvas)
Renders the content of a view.
Definition: view.h:312
Signal< void(FocusChangeEvent &)> & sig_focus_gained(bool use_capture=false)
View gained focus event.
std::shared_ptr< T > add_action(Types &&...args)
Definition: view.h:118
float last_baseline_offset(Canvas &canvas, float width)
Calculates the offset to the last baseline.
This class contains everything to construct a cursor - its data, default settings etc...
Definition: cursor_description.h:69
bool content_clipped() const
Content clipping flag.
Definition: signal.h:104
std::shared_ptr< T > add_child(Types &&...args)
Definition: view.h:99
void set_state_cascade(const std::string &name, bool value)
Sets the state for this view and all children recursively, until a manually set state of the same nam...
void set_cursor(const CursorDescription &cursor)
Set the cursor icon used when cursor is above this view.
Recognizes actions in a view and captures input for the duration of the action.
Definition: view_action.h:44
const ViewTree * view_tree() const
Tree in view hierachy.
virtual void render_border(Canvas &canvas)
Renders the border of a view.
Signal< void(PointerEvent &)> & sig_pointer_move(bool use_capture=false)
Pointer moved above view event.
Pointf from_screen_pos(const Pointf &pos)
Map from screen to local content coordinates.
std::shared_ptr< View > add_child()
Definition: view.h:106
Pointf to_root_pos(const Pointf &pos, bool relative_to_margin=false)
Map from local content to root content or margin (plus content, padding, border and margin) coordinat...
void set_geometry(const ViewGeometry &geometry)
bool hidden() const
Test if view is set to hidden.
Definition: signal.h:140
void stop_animations()
Stop all activate animation functions.
Canvas canvas() const
void set_focus()
Set this view as the focused view.
void update_cursor(DisplayWindow &window)
Update window cursor to the cursor used by this view.
FocusPolicy
Automatic focus policy.
Definition: focus_policy.h:34
bool needs_layout() const
Test if view geometry needs to be recalculated.
Base class for managing a tree of views.
Definition: view_tree.h:41
Signal< void(ResizeEvent &)> & sig_resize(bool use_capture=false)
Window resize event.
SlotContainer slots
Slot container helping with automatic disconnection of connected slots when the view is destroyed...
Definition: view.h:87
Style value resolver.
Definition: style_cascade.h:65
const Mat4f & view_transform() const
Current view transform.
const StyleCascade & style_cascade() const
Style cascade currently active for this view.
Signal< void(PointerEvent &)> & sig_pointer_enter(bool use_capture=false)
Pointer entering view geometry event.
Signal< void(PointerEvent &)> & sig_pointer_release(bool use_capture=false)
Pointer button released event.
bool is_static_position_and_visible() const
Test if view should participate in static layout calculations (layout_children)
2D (x,y) point structure - Float
Definition: point.h:71
void set_tab_index(unsigned int index)
Sets the tab index used for keyboard focus changes.
const ViewGeometry & geometry() const
Actual view position and size after layout.
virtual void child_added(const std::shared_ptr< View > &view)
Child view was added to this view.
Definition: view.h:321
void set_inherit_cursor()
Specify that the cursor icon is inherited from the parent view.
void set_needs_layout()
Forces recalculation of view geometry before next rendering.
Top-level window class.
Definition: display_window.h:100
bool state(const std::string &name) const
Test if a style state is currently set.
void draw_without_layout()
Render view and its children directly, without re-layout.
void set_hidden(bool value=true)
Hides a view from layout and rendering.
void prev_focus()
Give focus to the previous view in the keyboard tab index order.
void set_needs_render()
Signals this view needs to be rendered again.
std::shared_ptr< View > find_view_at(const Pointf &pos) const
Find descendant view at the specified content relative position.
void set_state(const std::string &name, bool value)
Set or clear style state.
float preferred_width(Canvas &canvas)
Calculates the preferred width of this view.