1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
// SPDX-License-Identifier: MIT OR Apache-2.0
use core::{ops::Deref, ptr::null_mut};
use oxivgl_sys::*;
use super::{
WidgetError,
obj::{AsLvHandle, Obj},
};
/// LVGL image widget. Wraps [`Obj`](super::obj::Obj) and `Deref`s to it for
/// style methods.
#[derive(Debug)]
pub struct Image<'p> {
obj: Obj<'p>,
}
impl<'p> AsLvHandle for Image<'p> {
fn lv_handle(&self) -> *mut lv_obj_t {
self.obj.lv_handle()
}
}
impl<'p> Deref for Image<'p> {
type Target = Obj<'p>;
fn deref(&self) -> &Obj<'p> {
&self.obj
}
}
/// Image content alignment within the widget bounds.
#[repr(u32)]
#[derive(Clone, Copy, Debug)]
pub enum ImageAlign {
/// Default alignment.
Default = 0,
/// Top-left corner.
TopLeft = 1,
/// Top-middle.
TopMid = 2,
/// Top-right corner.
TopRight = 3,
/// Bottom-left corner.
BottomLeft = 4,
/// Bottom-middle.
BottomMid = 5,
/// Bottom-right corner.
BottomRight = 6,
/// Left-middle.
LeftMid = 7,
/// Right-middle.
RightMid = 8,
/// Center.
Center = 9,
/// Stretch to fill.
Stretch = 11,
/// Tile/repeat to fill.
Tile = 12,
/// Contain (fit inside, keep aspect ratio).
Contain = 13,
/// Cover (fill area, keep aspect ratio, crop overflow).
Cover = 14,
}
impl<'p> Image<'p> {
/// Create an image widget as a child of `parent`. Returns
/// [`WidgetError::LvglNullPointer`] on OOM.
pub fn new(parent: &impl AsLvHandle) -> Result<Self, WidgetError> {
let parent_ptr = parent.lv_handle();
assert_ne!(parent_ptr, null_mut(), "Parent widget cannot be null");
// SAFETY: parent_ptr non-null (asserted above); lv_init() called via
// LvglDriver.
let handle = unsafe { lv_image_create(parent_ptr) };
if handle.is_null() { Err(WidgetError::LvglNullPointer) } else { Ok(Image { obj: Obj::from_raw(handle) }) }
}
/// Set image rotation in 0.1 degree units (e.g. 450 = 45 degrees).
pub fn set_rotation(&self, angle: i32) -> &Self {
unsafe { lv_image_set_rotation(self.lv_handle(), angle) };
self
}
/// Set uniform image scale (256 = 1.0x, 512 = 2.0x, 128 = 0.5x).
pub fn set_scale(&self, zoom: u32) -> &Self {
unsafe { lv_image_set_scale(self.lv_handle(), zoom) };
self
}
/// Set the pivot point for rotation and scaling.
pub fn set_pivot(&self, x: i32, y: i32) -> &Self {
unsafe { lv_image_set_pivot(self.lv_handle(), x, y) };
self
}
/// Set vertical image offset (scrolls the image content within the widget).
pub fn set_offset_y(&self, y: i32) -> &Self {
unsafe { lv_image_set_offset_y(self.lv_handle(), y) };
self
}
/// Set how the image is aligned/scaled within the widget area.
pub fn set_inner_align(&self, align: ImageAlign) -> &Self {
unsafe { lv_image_set_inner_align(self.lv_handle(), align as lv_image_align_t) };
self
}
/// Set the image source from a compiled image descriptor.
///
/// LVGL stores the raw pointer (`lv_image_t.src`), so the descriptor
/// must be `'static`. Use [`image_declare!`](crate::image_declare) to
/// obtain a safe `&'static lv_image_dsc_t` reference (spec §3.1).
///
/// # Example
///
/// ```ignore
/// oxivgl::image_declare!(my_icon);
/// let img = Image::new(&screen)?;
/// img.set_src(my_icon());
/// ```
pub fn set_src(&self, dsc: &'static lv_image_dsc_t) -> &Self {
// SAFETY: handle non-null (from Image::new); dsc is 'static and
// points to a valid lv_image_dsc_t compiled by oxivgl-build.
// LVGL stores the pointer (spec §3.1); 'static satisfies this.
unsafe { lv_image_set_src(self.obj.handle(), dsc as *const lv_image_dsc_t as *const core::ffi::c_void) };
self
}
/// Get image rotation in 0.1 degree units (e.g. 450 = 45 degrees).
pub fn get_rotation(&self) -> i32 {
// SAFETY: handle non-null (from Image::new).
unsafe { lv_image_get_rotation(self.lv_handle()) }
}
/// Get uniform image scale (256 = 1.0x, 512 = 2.0x, 128 = 0.5x).
pub fn get_scale(&self) -> i32 {
// SAFETY: handle non-null (from Image::new).
unsafe { lv_image_get_scale(self.lv_handle()) }
}
/// Get X-axis image scale (256 = 1.0x).
pub fn get_scale_x(&self) -> i32 {
// SAFETY: handle non-null (from Image::new).
unsafe { lv_image_get_scale_x(self.lv_handle()) }
}
/// Get horizontal image offset in pixels.
pub fn get_offset_x(&self) -> i32 {
// SAFETY: handle non-null (from Image::new).
unsafe { lv_image_get_offset_x(self.lv_handle()) }
}
/// Get vertical image offset in pixels.
pub fn get_offset_y(&self) -> i32 {
// SAFETY: handle non-null (from Image::new).
unsafe { lv_image_get_offset_y(self.lv_handle()) }
}
/// Get the inner alignment mode as raw `u32`.
///
/// Returns the raw `lv_image_align_t` value because `lv_image_align_t`
/// includes an internal `_AUTO_TRANSFORM = 10` variant not covered by
/// [`ImageAlign`].
pub fn get_inner_align(&self) -> u32 {
// SAFETY: handle non-null (from Image::new).
unsafe { lv_image_get_inner_align(self.lv_handle()) }
}
/// Get whether anti-aliasing is enabled for this image.
pub fn get_antialias(&self) -> bool {
// SAFETY: handle non-null (from Image::new).
unsafe { lv_image_get_antialias(self.lv_handle()) }
}
/// Get the source image width in pixels (before transform).
pub fn get_src_width(&self) -> i32 {
// SAFETY: handle non-null (from Image::new).
unsafe { lv_image_get_src_width(self.lv_handle()) }
}
/// Get the source image height in pixels (before transform).
pub fn get_src_height(&self) -> i32 {
// SAFETY: handle non-null (from Image::new).
unsafe { lv_image_get_src_height(self.lv_handle()) }
}
/// Set image source from a snapshot draw buffer.
///
/// LVGL stores the raw pointer — the [`Snapshot`](crate::snapshot::Snapshot)
/// must outlive the image widget. Store both in the View struct with the
/// snapshot field declared **after** the image field (Rust drops fields
/// in declaration order — image drops first, then snapshot).
#[cfg(not(target_os = "none"))]
pub fn set_src_snapshot(&self, snap: &crate::snapshot::Snapshot) -> &Self {
// SAFETY: handle non-null (from Image::new); snap.draw_buf_ptr() is
// valid and owned by the Snapshot. LVGL stores the pointer (spec §3.1);
// caller ensures snap outlives self via struct field ordering.
unsafe {
lv_image_set_src(
self.obj.handle(),
snap.draw_buf_ptr() as *const core::ffi::c_void,
)
};
self
}
/// Set the image source to a built-in LVGL symbol.
///
/// LVGL stores the pointer (`lv_image_t.src`); the symbol is `'static`
/// (compiled into the binary), satisfying spec §3.1.
///
/// ```ignore
/// use oxivgl::{symbols, widgets::Image};
/// let img = Image::new(&screen)?;
/// img.set_src_symbol(&symbols::SETTINGS);
/// ```
pub fn set_src_symbol(&self, symbol: &crate::symbols::Symbol) -> &Self {
// SAFETY: handle non-null (from Image::new); symbol.as_ptr() returns
// a 'static NUL-terminated string. LVGL detects the string source type
// by inspecting the first byte (lv_image.c:lv_image_src_get_type).
unsafe { lv_image_set_src(self.obj.handle(), symbol.as_ptr() as *const core::ffi::c_void) };
self
}
}