jcs.org
Serenity Operating System
1/*
2 * Copyright (c) 2018-2023, Andreas Kling <kling@serenityos.org>
3 *
4 * SPDX-License-Identifier: BSD-2-Clause
5 */
6
7#pragma once
8
9#include <AK/DeprecatedString.h>
10#include <AK/EnumBits.h>
11#include <AK/JsonObject.h>
12#include <AK/NonnullRefPtr.h>
13#include <AK/Optional.h>
14#include <AK/Variant.h>
15#include <LibCore/Object.h>
16#include <LibCore/Timer.h>
17#include <LibGUI/Event.h>
18#include <LibGUI/FocusPolicy.h>
19#include <LibGUI/Forward.h>
20#include <LibGUI/GML/AST.h>
21#include <LibGUI/Margins.h>
22#include <LibGUI/UIDimensions.h>
23#include <LibGfx/Color.h>
24#include <LibGfx/Forward.h>
25#include <LibGfx/Orientation.h>
26#include <LibGfx/Rect.h>
27#include <LibGfx/StandardCursor.h>
28
29namespace Core {
30namespace Registration {
31extern Core::ObjectClassRegistration registration_Widget;
32}
33}
34
35#define REGISTER_WIDGET(namespace_, class_name) \
36 namespace Core { \
37 namespace Registration { \
38 Core::ObjectClassRegistration registration_##class_name( \
39 #namespace_ "::" #class_name##sv, []() -> ErrorOr<NonnullRefPtr<Core::Object>> { return static_ptr_cast<Core::Object>(TRY(namespace_::class_name::try_create())); }, ®istration_Widget); \
40 } \
41 }
42
43namespace GUI {
44
45enum class HorizontalDirection {
46 Left,
47 Right
48};
49
50enum class VerticalDirection {
51 Up,
52 Down
53};
54
55constexpr VerticalDirection operator!(VerticalDirection const& other)
56{
57 if (other == VerticalDirection::Up)
58 return VerticalDirection::Down;
59 return VerticalDirection::Up;
60}
61
62constexpr VerticalDirection key_code_to_vertical_direction(KeyCode const& key)
63{
64 if (key == Key_Up)
65 return VerticalDirection::Up;
66 if (key == Key_Down)
67 return VerticalDirection::Down;
68 VERIFY_NOT_REACHED();
69}
70
71enum class AllowCallback {
72 No,
73 Yes
74};
75
76class Widget : public Core::Object {
77 C_OBJECT(Widget)
78public:
79 virtual ~Widget() override;
80
81 Layout* layout() { return m_layout.ptr(); }
82 Layout const* layout() const { return m_layout.ptr(); }
83 void set_layout(NonnullRefPtr<Layout>);
84
85 template<class T, class... Args>
86 ErrorOr<void> try_set_layout(Args&&... args)
87 {
88 auto layout = TRY(T::try_create(forward<Args>(args)...));
89 set_layout(*layout);
90 return {};
91 }
92
93 template<class T, class... Args>
94 inline void set_layout(Args&&... args)
95 {
96 auto layout = T::construct(forward<Args>(args)...);
97 set_layout(*layout);
98 }
99
100 UISize min_size() const { return m_min_size; }
101 void set_min_size(UISize const&);
102 void set_min_size(UIDimension width, UIDimension height) { set_min_size({ width, height }); }
103
104 UIDimension min_width() const { return m_min_size.width(); }
105 UIDimension min_height() const { return m_min_size.height(); }
106 void set_min_width(UIDimension width) { set_min_size(width, min_height()); }
107 void set_min_height(UIDimension height) { set_min_size(min_width(), height); }
108
109 UISize max_size() const { return m_max_size; }
110 void set_max_size(UISize const&);
111 void set_max_size(UIDimension width, UIDimension height) { set_max_size({ width, height }); }
112
113 UIDimension max_width() const { return m_max_size.width(); }
114 UIDimension max_height() const { return m_max_size.height(); }
115 void set_max_width(UIDimension width) { set_max_size(width, max_height()); }
116 void set_max_height(UIDimension height) { set_max_size(max_width(), height); }
117
118 UISize preferred_size() const { return m_preferred_size; }
119 void set_preferred_size(UISize const&);
120 void set_preferred_size(UIDimension width, UIDimension height) { set_preferred_size({ width, height }); }
121
122 UIDimension preferred_width() const { return m_preferred_size.width(); }
123 UIDimension preferred_height() const { return m_preferred_size.height(); }
124 void set_preferred_width(UIDimension width) { set_preferred_size(width, preferred_height()); }
125 void set_preferred_height(UIDimension height) { set_preferred_size(preferred_width(), height); }
126
127 virtual Optional<UISize> calculated_preferred_size() const;
128 virtual Optional<UISize> calculated_min_size() const;
129
130 UISize effective_preferred_size() const
131 {
132 auto effective_preferred_size = preferred_size();
133 if (effective_preferred_size.either_is(SpecialDimension::Shrink))
134 effective_preferred_size.replace_component_if_matching_with(SpecialDimension::Shrink, effective_min_size());
135 if (effective_preferred_size.either_is(SpecialDimension::Fit) && calculated_preferred_size().has_value())
136 effective_preferred_size.replace_component_if_matching_with(SpecialDimension::Fit, calculated_preferred_size().value());
137 return effective_preferred_size;
138 }
139
140 UISize effective_min_size() const
141 {
142 auto effective_min_size = min_size();
143 if (effective_min_size.either_is(SpecialDimension::Shrink) && calculated_min_size().has_value())
144 effective_min_size.replace_component_if_matching_with(SpecialDimension::Shrink, calculated_min_size().value());
145 return effective_min_size;
146 }
147
148 void set_fixed_size(UISize const& size)
149 {
150 VERIFY(size.has_only_int_values());
151 set_min_size(size);
152 set_max_size(size);
153 }
154
155 void set_fixed_size(UIDimension width, UIDimension height) { set_fixed_size({ width, height }); }
156
157 void set_fixed_width(UIDimension width)
158 {
159 VERIFY(width.is_int());
160 set_min_width(width);
161 set_max_width(width);
162 }
163
164 void set_fixed_height(UIDimension height)
165 {
166 VERIFY(height.is_int());
167 set_min_height(height);
168 set_max_height(height);
169 }
170
171 virtual bool is_visible_for_timer_purposes() const override;
172
173 bool has_tooltip() const { return !m_tooltip.is_empty(); }
174 DeprecatedString tooltip() const { return m_tooltip; }
175 void set_tooltip(DeprecatedString);
176
177 bool is_auto_focusable() const { return m_auto_focusable; }
178 void set_auto_focusable(bool auto_focusable) { m_auto_focusable = auto_focusable; }
179
180 bool is_enabled() const { return m_enabled; }
181 void set_enabled(bool);
182
183 bool updates_enabled() const { return m_updates_enabled; }
184 void set_updates_enabled(bool);
185
186 Gfx::IntRect relative_rect() const { return m_relative_rect; }
187 Gfx::IntPoint relative_position() const { return m_relative_rect.location(); }
188
189 Gfx::IntRect window_relative_rect() const;
190 Gfx::IntRect screen_relative_rect() const;
191
192 int x() const { return m_relative_rect.x(); }
193 int y() const { return m_relative_rect.y(); }
194 int width() const { return m_relative_rect.width(); }
195 int height() const { return m_relative_rect.height(); }
196 int length(Orientation orientation) const { return orientation == Orientation::Vertical ? height() : width(); }
197
198 virtual Margins content_margins() const { return { 0 }; }
199
200 Gfx::IntRect rect() const { return { 0, 0, width(), height() }; }
201 Gfx::IntSize size() const { return m_relative_rect.size(); }
202 Gfx::IntRect content_rect() const { return this->content_margins().applied_to(rect()); };
203 Gfx::IntSize content_size() const { return this->content_rect().size(); };
204
205 // Invalidate the widget (or an area thereof), causing a repaint to happen soon.
206 void update();
207 void update(Gfx::IntRect const&);
208
209 // Repaint the widget (or an area thereof) immediately.
210 void repaint();
211 void repaint(Gfx::IntRect const&);
212
213 bool is_focused() const;
214 void set_focus(bool, FocusSource = FocusSource::Programmatic);
215
216 bool focus_preempted() const { return m_focus_preempted; }
217 void set_focus_preempted(bool b) { m_focus_preempted = b; }
218
219 Function<void(bool const, const FocusSource)> on_focus_change;
220
221 // Returns true if this widget or one of its descendants is focused.
222 bool has_focus_within() const;
223
224 Widget* focus_proxy() { return m_focus_proxy; }
225 Widget const* focus_proxy() const { return m_focus_proxy; }
226 void set_focus_proxy(Widget*);
227
228 Vector<WeakPtr<Widget>>& focus_delegators() { return m_focus_delegators; }
229 Vector<WeakPtr<Widget>> const& focus_delegators() const { return m_focus_delegators; }
230
231 void set_focus_policy(FocusPolicy policy);
232 FocusPolicy focus_policy() const;
233
234 enum class ShouldRespectGreediness {
235 No = 0,
236 Yes
237 };
238 struct HitTestResult {
239 WeakPtr<Widget> widget;
240 Gfx::IntPoint local_position;
241 };
242 HitTestResult hit_test(Gfx::IntPoint, ShouldRespectGreediness = ShouldRespectGreediness::Yes);
243 Widget* child_at(Gfx::IntPoint) const;
244
245 void set_relative_rect(Gfx::IntRect const&);
246 void set_relative_rect(int x, int y, int width, int height) { set_relative_rect({ x, y, width, height }); }
247
248 void set_x(int x) { set_relative_rect(x, y(), width(), height()); }
249 void set_y(int y) { set_relative_rect(x(), y, width(), height()); }
250 void set_width(int width) { set_relative_rect(x(), y(), width, height()); }
251 void set_height(int height) { set_relative_rect(x(), y(), width(), height); }
252
253 void move_to(Gfx::IntPoint point) { set_relative_rect({ point, relative_rect().size() }); }
254 void move_to(int x, int y) { move_to({ x, y }); }
255 void resize(Gfx::IntSize size) { set_relative_rect({ relative_rect().location(), size }); }
256 void resize(int width, int height) { resize({ width, height }); }
257
258 void move_by(int x, int y) { move_by({ x, y }); }
259 void move_by(Gfx::IntPoint delta) { set_relative_rect({ relative_position().translated(delta), size() }); }
260
261 Gfx::ColorRole background_role() const { return m_background_role; }
262 void set_background_role(Gfx::ColorRole);
263
264 Gfx::ColorRole foreground_role() const { return m_foreground_role; }
265 void set_foreground_role(Gfx::ColorRole);
266
267 void set_autofill(bool b) { set_fill_with_background_color(b); }
268
269 Window* window()
270 {
271 if (auto* pw = parent_widget())
272 return pw->window();
273 return m_window;
274 }
275
276 Window const* window() const
277 {
278 if (auto* pw = parent_widget())
279 return pw->window();
280 return m_window;
281 }
282
283 void set_window(Window*);
284
285 Widget* parent_widget();
286 Widget const* parent_widget() const;
287
288 void set_fill_with_background_color(bool b) { m_fill_with_background_color = b; }
289 bool fill_with_background_color() const { return m_fill_with_background_color; }
290
291 Gfx::Font const& font() const { return *m_font; }
292
293 void set_font(Gfx::Font const*);
294 void set_font(Gfx::Font const& font) { set_font(&font); }
295
296 void set_font_family(DeprecatedString const&);
297 void set_font_size(unsigned);
298 void set_font_weight(unsigned);
299 void set_font_fixed_width(bool);
300
301 void notify_layout_changed(Badge<Layout>);
302 void invalidate_layout();
303
304 bool is_visible() const { return m_visible; }
305 void set_visible(bool);
306
307 bool spans_entire_window_horizontally() const;
308
309 bool is_greedy_for_hits() const { return m_greedy_for_hits; }
310 void set_greedy_for_hits(bool b) { m_greedy_for_hits = b; }
311
312 void move_to_front();
313 void move_to_back();
314
315 bool is_frontmost() const;
316 bool is_backmost() const;
317
318 Action* action_for_shortcut(Shortcut const&);
319
320 template<typename Callback>
321 void for_each_child_widget(Callback callback)
322 {
323 for_each_child([&](auto& child) {
324 if (is<Widget>(child))
325 return callback(verify_cast<Widget>(child));
326 return IterationDecision::Continue;
327 });
328 }
329
330 Vector<Widget&> child_widgets() const;
331
332 void do_layout();
333
334 Gfx::Palette palette() const;
335 void set_palette(Gfx::Palette&);
336
337 DeprecatedString title() const;
338 void set_title(DeprecatedString);
339
340 Margins const& grabbable_margins() const { return m_grabbable_margins; }
341 void set_grabbable_margins(Margins const&);
342
343 Gfx::IntRect relative_non_grabbable_rect() const;
344
345 Function<void(StringView)> on_emoji_input;
346
347 void set_accepts_command_palette(bool b) { m_accepts_command_palette = b; }
348 bool accepts_command_palette() const { return m_accepts_command_palette; }
349
350 virtual Gfx::IntRect children_clip_rect() const;
351
352 AK::Variant<Gfx::StandardCursor, NonnullRefPtr<Gfx::Bitmap const>> const& override_cursor() const { return m_override_cursor; }
353 void set_override_cursor(AK::Variant<Gfx::StandardCursor, NonnullRefPtr<Gfx::Bitmap const>>);
354
355 using UnregisteredChildHandler = ErrorOr<NonnullRefPtr<Core::Object>>(DeprecatedString const&);
356 ErrorOr<void> load_from_gml(StringView);
357 ErrorOr<void> load_from_gml(StringView, UnregisteredChildHandler);
358
359 // FIXME: remove this when all uses of shrink_to_fit are eliminated
360 void set_shrink_to_fit(bool);
361 bool is_shrink_to_fit() const { return preferred_width().is_shrink() || preferred_height().is_shrink(); }
362
363 bool has_pending_drop() const;
364
365 // In order for others to be able to call this, it needs to be public.
366 virtual ErrorOr<void> load_from_gml_ast(NonnullRefPtr<GUI::GML::Node const> ast, UnregisteredChildHandler);
367
368 ErrorOr<void> add_spacer();
369
370protected:
371 Widget();
372
373 virtual void event(Core::Event&) override;
374
375 // This is called after children have been painted.
376 virtual void second_paint_event(PaintEvent&);
377
378 virtual void layout_relevant_change_occurred();
379 virtual void custom_layout() { }
380 virtual void did_change_font() { }
381 virtual void did_layout() { }
382 virtual void paint_event(PaintEvent&);
383 virtual void resize_event(ResizeEvent&);
384 virtual void show_event(ShowEvent&);
385 virtual void hide_event(HideEvent&);
386 virtual void keydown_event(KeyEvent&);
387 virtual void keyup_event(KeyEvent&);
388 virtual void mousemove_event(MouseEvent&);
389 virtual void mousedown_event(MouseEvent&);
390 virtual void mouseup_event(MouseEvent&);
391 virtual void mousewheel_event(MouseEvent&);
392 virtual void doubleclick_event(MouseEvent&);
393 virtual void context_menu_event(ContextMenuEvent&);
394 virtual void focusin_event(FocusEvent&);
395 virtual void focusout_event(FocusEvent&);
396 virtual void enter_event(Core::Event&);
397 virtual void leave_event(Core::Event&);
398 virtual void child_event(Core::ChildEvent&) override;
399 virtual void change_event(Event&);
400 virtual void drag_enter_event(DragEvent&);
401 virtual void drag_move_event(DragEvent&);
402 virtual void drag_leave_event(Event&);
403 virtual void drop_event(DropEvent&);
404 virtual void theme_change_event(ThemeChangeEvent&);
405 virtual void fonts_change_event(FontsChangeEvent&);
406 virtual void screen_rects_change_event(ScreenRectsChangeEvent&);
407 virtual void applet_area_rect_change_event(AppletAreaRectChangeEvent&);
408
409 virtual void did_begin_inspection() override;
410 virtual void did_end_inspection() override;
411
412 void show_or_hide_tooltip();
413
414 void add_focus_delegator(Widget*);
415 void remove_focus_delegator(Widget*);
416
417private:
418 virtual bool is_widget() const final { return true; }
419
420 void handle_paint_event(PaintEvent&);
421 void handle_resize_event(ResizeEvent&);
422 void handle_mousedown_event(MouseEvent&);
423 void handle_mousedoubleclick_event(MouseEvent&);
424 void handle_mouseup_event(MouseEvent&);
425 void handle_keydown_event(KeyEvent&);
426 void handle_enter_event(Core::Event&);
427 void handle_leave_event(Core::Event&);
428 void focus_previous_widget(FocusSource, bool siblings_only);
429 void focus_next_widget(FocusSource, bool siblings_only);
430
431 // HACK: These are used as property getters for the fixed_* size property aliases.
432 int dummy_fixed_width() { return 0; }
433 int dummy_fixed_height() { return 0; }
434 Gfx::IntSize dummy_fixed_size() { return {}; }
435
436 Window* m_window { nullptr };
437 RefPtr<Layout> m_layout;
438
439 Gfx::IntRect m_relative_rect;
440 Gfx::ColorRole m_background_role;
441 Gfx::ColorRole m_foreground_role;
442 NonnullRefPtr<Gfx::Font const> m_font;
443 DeprecatedString m_tooltip;
444
445 UISize m_min_size { SpecialDimension::Shrink };
446 UISize m_max_size { SpecialDimension::Grow };
447 UISize m_preferred_size { SpecialDimension::Grow };
448 Margins m_grabbable_margins;
449
450 bool m_fill_with_background_color { false };
451 bool m_visible { true };
452 bool m_greedy_for_hits { false };
453 bool m_auto_focusable { true };
454 bool m_focus_preempted { false };
455 bool m_enabled { true };
456 bool m_updates_enabled { true };
457 bool m_accepts_command_palette { true };
458 bool m_default_font { true };
459
460 NonnullRefPtr<Gfx::PaletteImpl> m_palette;
461 DeprecatedString m_title { DeprecatedString::empty() };
462
463 WeakPtr<Widget> m_focus_proxy;
464 Vector<WeakPtr<Widget>> m_focus_delegators;
465 FocusPolicy m_focus_policy { FocusPolicy::NoFocus };
466
467 AK::Variant<Gfx::StandardCursor, NonnullRefPtr<Gfx::Bitmap const>> m_override_cursor { Gfx::StandardCursor::None };
468};
469
470inline Widget* Widget::parent_widget()
471{
472 if (parent() && is<Widget>(*parent()))
473 return &verify_cast<Widget>(*parent());
474 return nullptr;
475}
476inline Widget const* Widget::parent_widget() const
477{
478 if (parent() && is<Widget>(*parent()))
479 return &verify_cast<Widget const>(*parent());
480 return nullptr;
481}
482}
483
484template<>
485inline bool Core::Object::fast_is<GUI::Widget>() const { return is_widget(); }
486
487template<>
488struct AK::Formatter<GUI::Widget> : AK::Formatter<Core::Object> {
489};