The Battle for Wesnoth  1.19.4+dev
top_level_drawable.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2007 - 2024
3  Part of the Battle for Wesnoth Project https://www.wesnoth.org/
4 
5  This program is free software; you can redistribute it and/or modify
6  it under the terms of the GNU General Public License as published by
7  the Free Software Foundation; either version 2 of the License, or
8  (at your option) any later version.
9  This program is distributed in the hope that it will be useful,
10  but WITHOUT ANY WARRANTY.
11 
12  See the COPYING file for more details.
13 */
14 
15 #pragma once
16 
17 #include "sdl/rect.hpp"
18 
19 namespace gui2
20 {
21 
22 /**
23  * A top-level drawable item (TLD), such as a window.
24  *
25  * For now, TLDs keep track of where they are on the screen on their own.
26  * They must draw themselves when requested via expose().
27  *
28  * The TLD interface will be called in the following order:
29  * - update()
30  * - layout()
31  * - render()
32  * - screen_location()
33  * - zero or more expose() calls
34  *
35  * It can be assumed that events will have been processed before TLD
36  * interface calls commence, and that no more events will be processed
37  * until all TLD interfaces have been called. As such the main program
38  * loop will usually be:
39  * 1. process events
40  * 2. call update() on all TLDs
41  * 3. call layout() on all TLDs
42  * 4. call render() on all TLDs
43  * 5. call expose() on TLDs as appropriate
44  *
45  * TLDs are responsible for propagating these calls to their children.
46  *
47  * This process is loosely based on the GTK drawing model. Ref:
48  * - https://docs.gtk.org/gtk3/drawing-model.html
49  * - https://docs.gtk.org/gtk4/drawing-model.html
50  */
52 {
53 protected:
55  virtual ~top_level_drawable();
56 
57  // These make sure the TLD is registered.
62 
63 public:
64  /**
65  * Update state and any parameters that may effect layout, or any of
66  * the later stages.
67  *
68  * In general this should be used to make changes to things that will
69  * affect the visible state of the drawable. This can include changing
70  * the drawable's size or position, or updating animation frames to
71  * show the appropriate image for the current time. Exact usage is up
72  * to the drawable to decide.
73  *
74  * This interface is optional.
75  */
76  virtual void update() {}
77 
78  /**
79  * Finalize the size and position of the drawable and its children,
80  * and invalidate any regions requiring redraw.
81  *
82  * Visibly changed screen locations should be invalidated using
83  * draw_manager::invalidate_region(), both in the previous location
84  * and in the new location if different.
85  *
86  * TLDs must not perform any actual drawing during layout.
87  *
88  * This interface is optional.
89  */
90  virtual void layout() {};
91 
92  /**
93  * Perform any internal rendering necessary to prepare the drawable.
94  *
95  * For example if the drawable has an offscreen buffer it manages,
96  * it should ensure this buffer is up to date.
97  *
98  * TLDs should also invalidate any regions visibly changed by this call.
99  *
100  * This interface is optional.
101  */
102  virtual void render() {}
103 
104  /**
105  * Draw the portion of the drawable intersecting @p region to the screen.
106  *
107  * TLDs must not invalidate regions during expose. Only drawing must
108  * occur, with no modification of layout.
109  *
110  * Implementation of this interface is mandatory.
111  *
112  * @param region The region to expose, in absolute draw-space
113  * coordinates.
114  * @returns True if anything was drawn, false otherwise.
115  */
116  virtual bool expose(const rect& region) = 0;
117 
118  /**
119  * The location of the TLD on the screen, in drawing coordinates.
120  *
121  * This will be used to determine the region (if any) to expose.
122  *
123  * Implementation of this interface is mandatory.
124  */
125  virtual rect screen_location() = 0;
126 };
127 
128 } // namespace gui2
A top-level drawable item (TLD), such as a window.
virtual bool expose(const rect &region)=0
Draw the portion of the drawable intersecting region to the screen.
virtual rect screen_location()=0
The location of the TLD on the screen, in drawing coordinates.
top_level_drawable & operator=(const top_level_drawable &)
virtual void render()
Perform any internal rendering necessary to prepare the drawable.
virtual void layout()
Finalize the size and position of the drawable and its children, and invalidate any regions requiring...
virtual void update()
Update state and any parameters that may effect layout, or any of the later stages.
Generic file dialog.
Contains the SDL_Rect helper code.
An abstract description of a rectangle with integer coordinates.
Definition: rect.hpp:47