Update image / image button API

CHANGELOG.markdown

@@ -14,6 +14,7 @@
 - Redesigned progress bar API
 - Redesigned color editor/picker API
 - Redesigned child window API (previously known as child frame)
+- Redesigned image / image button API
 - Updated layout API
 - Renderer errors implement std::error::Error
 - Glium renderer re-exports imgui and glium

imgui-examples/examples/custom_textures.rs

@@ -74,7 +74,7 @@ impl CustomTexturesApp {
                 ui.text(im_str!("Hello textures!"));
                 if let Some(my_texture_id) = self.my_texture_id {
                     ui.text("Some generated texture");
-                    ui.image(my_texture_id, [100.0, 100.0]).build();
+                    Image::new(my_texture_id, [100.0, 100.0]).build(ui);
                 }
 
                 if let Some(lenna) = &self.lenna {
@@ -111,7 +111,7 @@ impl Lenna {
     }
 
     fn show(&self, ui: &Ui) {
-        ui.image(self.texture_id, self.size).build();
+        Image::new(self.texture_id, self.size).build(ui);
     }
 }
 

imgui-gfx-examples/examples/custom_textures.rs

@@ -68,7 +68,7 @@ impl CustomTexturesApp {
                 ui.text(im_str!("Hello textures!"));
                 if let Some(my_texture_id) = self.my_texture_id {
                     ui.text("Some generated texture");
-                    ui.image(my_texture_id, [100.0, 100.0]).build();
+                    Image::new(my_texture_id, [100.0, 100.0]).build(ui);
                 }
 
                 if let Some(lenna) = &self.lenna {
@@ -111,7 +111,7 @@ impl Lenna {
     }
 
     fn show(&self, ui: &Ui) {
-        ui.image(self.texture_id, self.size).build();
+        Image::new(self.texture_id, self.size).build(ui);
     }
 }
 

src/image.rs

@@ -1,160 +0,0 @@
-use std::marker::PhantomData;
-use std::os::raw::c_void;
-
-use crate::render::renderer::TextureId;
-use crate::sys;
-use crate::Ui;
-
-/// Represent an image about to be drawn.
-/// See [`Ui::image`].
-///
-/// Create your image using the builder pattern then [`Image::build`] it.
-#[must_use]
-pub struct Image<'ui> {
-    texture_id: TextureId,
-    size: [f32; 2],
-    uv0: [f32; 2],
-    uv1: [f32; 2],
-    tint_col: [f32; 4],
-    border_col: [f32; 4],
-    _phantom: PhantomData<&'ui Ui<'ui>>,
-}
-
-impl<'ui> Image<'ui> {
-    pub fn new(_: &Ui<'ui>, texture_id: TextureId, size: [f32; 2]) -> Self {
-        const DEFAULT_UV0: [f32; 2] = [0.0, 0.0];
-        const DEFAULT_UV1: [f32; 2] = [1.0, 1.0];
-        const DEFAULT_TINT_COL: [f32; 4] = [1.0, 1.0, 1.0, 1.0];
-        const DEFAULT_BORDER_COL: [f32; 4] = [0.0, 0.0, 0.0, 0.0];
-        Image {
-            texture_id,
-            size,
-            uv0: DEFAULT_UV0,
-            uv1: DEFAULT_UV1,
-            tint_col: DEFAULT_TINT_COL,
-            border_col: DEFAULT_BORDER_COL,
-            _phantom: PhantomData,
-        }
-    }
-    /// Set size (default based on texture)
-    pub fn size(mut self, size: [f32; 2]) -> Self {
-        self.size = size;
-        self
-    }
-    /// Set uv0 (default `[0.0, 0.0]`)
-    pub fn uv0(mut self, uv0: [f32; 2]) -> Self {
-        self.uv0 = uv0;
-        self
-    }
-    /// Set uv1 (default `[1.0, 1.0]`)
-    pub fn uv1(mut self, uv1: [f32; 2]) -> Self {
-        self.uv1 = uv1;
-        self
-    }
-    /// Set tint color (default: no tint color)
-    pub fn tint_col(mut self, tint_col: [f32; 4]) -> Self {
-        self.tint_col = tint_col;
-        self
-    }
-    /// Set border color (default: no border)
-    pub fn border_col(mut self, border_col: [f32; 4]) -> Self {
-        self.border_col = border_col;
-        self
-    }
-    /// Draw image where the cursor currently is
-    pub fn build(self) {
-        unsafe {
-            sys::igImage(
-                self.texture_id.id() as *mut c_void,
-                self.size.into(),
-                self.uv0.into(),
-                self.uv1.into(),
-                self.tint_col.into(),
-                self.border_col.into(),
-            );
-        }
-    }
-}
-
-/// Represent an image button about to be drawn.
-/// See [`Ui::image_button`].
-///
-/// Create your image button using the builder pattern then [`ImageButton::build`] it.
-#[must_use]
-pub struct ImageButton<'ui> {
-    texture_id: TextureId,
-    size: [f32; 2],
-    uv0: [f32; 2],
-    uv1: [f32; 2],
-    frame_padding: i32,
-    bg_col: [f32; 4],
-    tint_col: [f32; 4],
-    _phantom: PhantomData<&'ui Ui<'ui>>,
-}
-
-impl<'ui> ImageButton<'ui> {
-    pub fn new(_: &Ui<'ui>, texture_id: TextureId, size: [f32; 2]) -> Self {
-        const DEFAULT_UV0: [f32; 2] = [0.0, 0.0];
-        const DEFAULT_UV1: [f32; 2] = [1.0, 1.0];
-        const DEFAULT_FRAME_PADDING: i32 = -1;
-        const DEFAULT_BG_COL: [f32; 4] = [0.0, 0.0, 0.0, 0.0];
-        const DEFAULT_TINT_COL: [f32; 4] = [1.0, 1.0, 1.0, 1.0];
-        ImageButton {
-            texture_id,
-            size: size,
-            uv0: DEFAULT_UV0,
-            uv1: DEFAULT_UV1,
-            frame_padding: DEFAULT_FRAME_PADDING,
-            bg_col: DEFAULT_BG_COL,
-            tint_col: DEFAULT_TINT_COL,
-            _phantom: PhantomData,
-        }
-    }
-    /// Set size (default based on texture)
-    pub fn size(mut self, size: [f32; 2]) -> Self {
-        self.size = size;
-        self
-    }
-    /// Set uv0 (default `[0.0, 0.0]`)
-    pub fn uv0(mut self, uv0: [f32; 2]) -> Self {
-        self.uv0 = uv0;
-        self
-    }
-    /// Set uv1 (default `[1.0, 1.0]`)
-    pub fn uv1(mut self, uv1: [f32; 2]) -> Self {
-        self.uv1 = uv1;
-        self
-    }
-    /// Set frame padding (default: uses frame padding from style).
-    /// frame_padding < 0: uses frame padding from style (default)
-    /// frame_padding = 0: no framing
-    /// frame_padding > 0: set framing size
-    pub fn frame_padding(mut self, frame_padding: i32) -> Self {
-        self.frame_padding = frame_padding.into();
-        self
-    }
-    /// Set tint color (default: no tint color)
-    pub fn tint_col(mut self, tint_col: [f32; 4]) -> Self {
-        self.tint_col = tint_col;
-        self
-    }
-    /// Set background color (default: no background color)
-    pub fn background_col(mut self, bg_col: [f32; 4]) -> Self {
-        self.bg_col = bg_col;
-        self
-    }
-    /// Draw image button where the cursor currently is
-    pub fn build(self) -> bool {
-        unsafe {
-            sys::igImageButton(
-                self.texture_id.id() as *mut c_void,
-                self.size.into(),
-                self.uv0.into(),
-                self.uv1.into(),
-                self.frame_padding,
-                self.bg_col.into(),
-                self.tint_col.into(),
-            )
-        }
-    }
-}

src/legacy.rs

@@ -2,8 +2,10 @@
 use bitflags::bitflags;
 use std::os::raw::c_int;
 
+use crate::render::renderer::TextureId;
 use crate::string::ImStr;
 use crate::widget::color_editors::*;
+use crate::widget::image::{Image, ImageButton};
 use crate::widget::progress_bar::ProgressBar;
 use crate::window::{Window, WindowFlags, WindowFocusedFlags};
 use crate::{Id, Ui};
@@ -346,3 +348,14 @@ impl<'ui> Ui<'ui> {
         size.into()
     }
 }
+
+impl<'ui> Ui<'ui> {
+    #[deprecated(since = "0.2.0", note = "use imgui::Image::new(...) instead")]
+    pub fn image(&self, texture: TextureId, size: [f32; 2]) -> Image {
+        Image::new(texture, size)
+    }
+    #[deprecated(since = "0.2.0", note = "use imgui::ImageButton::new(...) instead")]
+    pub fn image_button(&self, texture: TextureId, size: [f32; 2]) -> ImageButton {
+        ImageButton::new(texture, size)
+    }
+}

src/lib.rs

@@ -19,7 +19,6 @@ pub use self::fonts::atlas::*;
 pub use self::fonts::font::*;
 pub use self::fonts::glyph::*;
 pub use self::fonts::glyph_ranges::*;
-pub use self::image::{Image, ImageButton};
 pub use self::input::keyboard::*;
 pub use self::input::mouse::*;
 pub use self::input_widget::{
@@ -44,6 +43,7 @@ pub use self::style::*;
 pub use self::trees::{CollapsingHeader, TreeNode};
 pub use self::utils::*;
 pub use self::widget::color_editors::*;
+pub use self::widget::image::*;
 pub use self::widget::progress_bar::*;
 pub use self::window::child_window::*;
 pub use self::window::*;
@@ -55,7 +55,6 @@ mod columns;
 mod context;
 mod drag;
 mod fonts;
-mod image;
 mod input;
 mod input_widget;
 pub mod internal;
@@ -624,20 +623,6 @@ impl<'ui> Ui<'ui> {
     }
 }
 
-// Image
-impl<'ui> Ui<'ui> {
-    pub fn image(&self, texture: TextureId, size: [f32; 2]) -> Image {
-        Image::new(self, texture, size)
-    }
-}
-
-// ImageButton
-impl<'ui> Ui<'ui> {
-    pub fn image_button(&self, texture: TextureId, size: [f32; 2]) -> ImageButton {
-        ImageButton::new(self, texture, size)
-    }
-}
-
 impl<'ui> Ui<'ui> {
     /// Calculate the size required for a given text string.
     ///

src/widget/image.rs

@@ -0,0 +1,145 @@
+use std::os::raw::c_void;
+
+use crate::render::renderer::TextureId;
+use crate::sys;
+use crate::Ui;
+
+/// Builder for an image widget
+#[derive(Copy, Clone, Debug)]
+#[must_use]
+pub struct Image {
+    texture_id: TextureId,
+    size: [f32; 2],
+    uv0: [f32; 2],
+    uv1: [f32; 2],
+    tint_col: [f32; 4],
+    border_col: [f32; 4],
+}
+
+impl Image {
+    /// Creates a new image builder with the given texture and size
+    pub fn new(texture_id: TextureId, size: [f32; 2]) -> Image {
+        Image {
+            texture_id,
+            size,
+            uv0: [0.0, 0.0],
+            uv1: [1.0, 1.0],
+            tint_col: [1.0, 1.0, 1.0, 1.0],
+            border_col: [0.0, 0.0, 0.0, 0.0],
+        }
+    }
+    /// Sets the image size
+    pub fn size(mut self, size: [f32; 2]) -> Self {
+        self.size = size;
+        self
+    }
+    /// Sets uv0 (default `[0.0, 0.0]`)
+    pub fn uv0(mut self, uv0: [f32; 2]) -> Self {
+        self.uv0 = uv0;
+        self
+    }
+    /// Sets uv1 (default `[1.0, 1.0]`)
+    pub fn uv1(mut self, uv1: [f32; 2]) -> Self {
+        self.uv1 = uv1;
+        self
+    }
+    /// Sets the tint color (default: no tint color)
+    pub fn tint_col(mut self, tint_col: [f32; 4]) -> Self {
+        self.tint_col = tint_col;
+        self
+    }
+    /// Sets the border color (default: no border)
+    pub fn border_col(mut self, border_col: [f32; 4]) -> Self {
+        self.border_col = border_col;
+        self
+    }
+    /// Builds the image
+    pub fn build(self, _: &Ui) {
+        unsafe {
+            sys::igImage(
+                self.texture_id.id() as *mut c_void,
+                self.size.into(),
+                self.uv0.into(),
+                self.uv1.into(),
+                self.tint_col.into(),
+                self.border_col.into(),
+            );
+        }
+    }
+}
+
+/// Builder for an image button widget
+#[derive(Copy, Clone, Debug)]
+#[must_use]
+pub struct ImageButton {
+    texture_id: TextureId,
+    size: [f32; 2],
+    uv0: [f32; 2],
+    uv1: [f32; 2],
+    frame_padding: i32,
+    bg_col: [f32; 4],
+    tint_col: [f32; 4],
+}
+
+impl ImageButton {
+    /// Creates a new image button builder with the given texture and size
+    pub fn new(texture_id: TextureId, size: [f32; 2]) -> ImageButton {
+        ImageButton {
+            texture_id,
+            size,
+            uv0: [0.0, 0.0],
+            uv1: [1.0, 1.0],
+            frame_padding: -1,
+            bg_col: [0.0, 0.0, 0.0, 0.0],
+            tint_col: [1.0, 1.0, 1.0, 1.0],
+        }
+    }
+    /// Sets the image button size
+    pub fn size(mut self, size: [f32; 2]) -> Self {
+        self.size = size;
+        self
+    }
+    /// Sets uv0 (default `[0.0, 0.0]`)
+    pub fn uv0(mut self, uv0: [f32; 2]) -> Self {
+        self.uv0 = uv0;
+        self
+    }
+    /// Sets uv1 (default `[1.0, 1.0]`)
+    pub fn uv1(mut self, uv1: [f32; 2]) -> Self {
+        self.uv1 = uv1;
+        self
+    }
+    /// Sets the frame padding (default: uses frame padding from style).
+    ///
+    /// - `< 0`: uses frame padding from style (default)
+    /// - `= 0`: no framing
+    /// - `> 0`: set framing size
+    pub fn frame_padding(mut self, frame_padding: i32) -> Self {
+        self.frame_padding = frame_padding.into();
+        self
+    }
+    /// Sets the background color (default: no background color)
+    pub fn background_col(mut self, bg_col: [f32; 4]) -> Self {
+        self.bg_col = bg_col;
+        self
+    }
+    /// Sets the tint color (default: no tint color)
+    pub fn tint_col(mut self, tint_col: [f32; 4]) -> Self {
+        self.tint_col = tint_col;
+        self
+    }
+    /// Builds the image button
+    pub fn build(self, _: &Ui) {
+        unsafe {
+            sys::igImageButton(
+                self.texture_id.id() as *mut c_void,
+                self.size.into(),
+                self.uv0.into(),
+                self.uv1.into(),
+                self.frame_padding,
+                self.bg_col.into(),
+                self.tint_col.into(),
+            );
+        }
+    }
+}

src/widget/mod.rs

@@ -1,4 +1,5 @@
 pub mod color_editors;
+pub mod image;
 pub mod misc;
 pub mod progress_bar;
 pub mod text;