From 9d47482a11e79484d61afdb355e60fe5636f4f79 Mon Sep 17 00:00:00 2001 From: Joonas Javanainen Date: Sat, 4 Nov 2017 11:11:21 +0200 Subject: [PATCH] Add docs, export all config enums --- src/color_editors.rs | 59 +++++++++++++++++++++++++++++++++++++++++++- src/lib.rs | 5 +++- 2 files changed, 62 insertions(+), 2 deletions(-) diff --git a/src/color_editors.rs b/src/color_editors.rs index 0bf5245..f11c935 100644 --- a/src/color_editors.rs +++ b/src/color_editors.rs @@ -1,16 +1,21 @@ +#![warn(missing_docs)] use imgui_sys; use std::marker::PhantomData; use std::ptr; use {ImGuiColorEditFlags, ImStr, Ui}; +/// Mutable reference to an editable color value. #[derive(Debug)] pub enum EditableColor<'p> { + /// Color value with three float components (e.g. RGB). Float3(&'p mut [f32; 3]), + /// Color value with four float components (e.g. RGBA). Float4(&'p mut [f32; 4]), } impl<'p> EditableColor<'p> { + /// Returns an unsafe mutable pointer to the color slice's buffer. fn as_mut_ptr(&mut self) -> *mut f32 { match *self { EditableColor::Float3(ref mut value) => value.as_mut_ptr(), @@ -27,32 +32,47 @@ impl<'p> From<&'p mut [f32; 4]> for EditableColor<'p> { fn from(value: &'p mut [f32; 4]) -> EditableColor<'p> { EditableColor::Float4(value) } } +/// Color editor mode. #[derive(Copy, Clone, Debug, PartialEq, Eq)] pub enum ColorEditMode { + /// Edit as RGB(A). RGB, + /// Edit as HSV(A). HSV, + /// Edit as hex (e.g. #AABBCC(DD)) HEX, } +/// Color picker hue/saturation/value editor mode. #[derive(Copy, Clone, Debug, PartialEq, Eq)] pub enum ColorPickerMode { + /// Use a bar for hue, rectangle for saturation/value. HueBar, + /// Use a wheel for hue, triangle for saturation/value. HueWheel, } +/// Color component formatting. #[derive(Copy, Clone, Debug, PartialEq, Eq)] pub enum EditableColorFormat { + /// Display values formatted as 0..255. U8, + /// Display values formatted as 0.0..1.0. Float, } +/// Color editor preview style. #[derive(Copy, Clone, Debug, PartialEq, Eq)] pub enum EditableColorPreview { + /// Don't show the alpha component. Opaque, + /// Half of the preview area shows the alpha component using a checkerboard pattern. HalfAlpha, + /// Show the alpha component using a checkerboard pattern. Alpha, } +/// Builder for a color editor widget. #[must_use] pub struct ColorEdit<'ui, 'p> { label: &'p ImStr, @@ -62,6 +82,7 @@ pub struct ColorEdit<'ui, 'p> { } impl<'ui, 'p> ColorEdit<'ui, 'p> { + /// Constructs a new color editor builder. pub fn new(_: &Ui<'ui>, label: &'p ImStr, value: EditableColor<'p>) -> Self { ColorEdit { label, @@ -70,51 +91,63 @@ impl<'ui, 'p> ColorEdit<'ui, 'p> { _phantom: PhantomData, } } + /// Replaces all current settings with the given flags. #[inline] pub fn flags(mut self, flags: ImGuiColorEditFlags) -> Self { self.flags = flags; self } + /// Enables/disables the use of the alpha component. #[inline] pub fn alpha(mut self, value: bool) -> Self { self.flags.set(ImGuiColorEditFlags::NoAlpha, !value); self } + /// Enables/disables the picker that appears when clicking on colored square. #[inline] pub fn picker(mut self, value: bool) -> Self { self.flags.set(ImGuiColorEditFlags::NoPicker, !value); self } + /// Enables/disables toggling of the options menu when right-clicking on inputs or the small + /// preview. #[inline] pub fn options(mut self, value: bool) -> Self { self.flags.set(ImGuiColorEditFlags::NoOptions, !value); self } + /// Enables/disables the colored square preview next to the inputs. #[inline] pub fn small_preview(mut self, value: bool) -> Self { self.flags.set(ImGuiColorEditFlags::NoSmallPreview, !value); self } + /// Enables/disables the input sliders/text widgets. #[inline] pub fn inputs(mut self, value: bool) -> Self { self.flags.set(ImGuiColorEditFlags::NoInputs, !value); self } + /// Enables/disables the tooltip that appears when hovering the preview. #[inline] pub fn tooltip(mut self, value: bool) -> Self { self.flags.set(ImGuiColorEditFlags::NoTooltip, !value); self } + /// Enables/disables display of the inline text label (the label is in any case forwarded to + /// the tooltip and picker). #[inline] pub fn label(mut self, value: bool) -> Self { self.flags.set(ImGuiColorEditFlags::NoLabel, !value); self } + /// Enables/disables the vertical alpha bar/gradient in the color picker. #[inline] pub fn alpha_bar(mut self, value: bool) -> Self { self.flags.set(ImGuiColorEditFlags::AlphaBar, value); self } + /// Sets the preview style. #[inline] pub fn preview(mut self, preview: EditableColorPreview) -> Self { self.flags.set( @@ -127,11 +160,15 @@ impl<'ui, 'p> ColorEdit<'ui, 'p> { ); self } + /// (WIP) Currently only disables 0.0..1.0 limits in RGBA edition. + /// + /// Note: you probably want to use EditableColorFormat::Float as well. #[inline] pub fn hdr(mut self, value: bool) -> Self { self.flags.set(ImGuiColorEditFlags::HDR, value); self } + /// Sets the color editor mode. #[inline] pub fn mode(mut self, mode: ColorEditMode) -> Self { self.flags.set( @@ -148,6 +185,7 @@ impl<'ui, 'p> ColorEdit<'ui, 'p> { ); self } + /// Sets the formatting style of color components. #[inline] pub fn format(mut self, format: EditableColorFormat) -> Self { self.flags.set( @@ -160,6 +198,7 @@ impl<'ui, 'p> ColorEdit<'ui, 'p> { ); self } + /// Builds the color editor. pub fn build(self) -> bool { match self.value { EditableColor::Float3(value) => unsafe { @@ -172,7 +211,7 @@ impl<'ui, 'p> ColorEdit<'ui, 'p> { } } - +/// Builder for a color picker widget. #[must_use] pub struct ColorPicker<'ui, 'p> { label: &'p ImStr, @@ -183,6 +222,7 @@ pub struct ColorPicker<'ui, 'p> { } impl<'ui, 'p> ColorPicker<'ui, 'p> { + /// Constructs a new color picker builder. pub fn new(_: &Ui<'ui>, label: &'p ImStr, value: EditableColor<'p>) -> Self { ColorPicker { label, @@ -192,46 +232,56 @@ impl<'ui, 'p> ColorPicker<'ui, 'p> { _phantom: PhantomData, } } + /// Replaces all current settings with the given flags. #[inline] pub fn flags(mut self, flags: ImGuiColorEditFlags) -> Self { self.flags = flags; self } + /// Enables/disables the use of the alpha component. #[inline] pub fn alpha(mut self, value: bool) -> Self { self.flags.set(ImGuiColorEditFlags::NoAlpha, !value); self } + /// Enables/disables the colored square preview next to the inputs. #[inline] pub fn small_preview(mut self, value: bool) -> Self { self.flags.set(ImGuiColorEditFlags::NoSmallPreview, !value); self } + /// Enables/disables the input sliders/text widgets. #[inline] pub fn inputs(mut self, value: bool) -> Self { self.flags.set(ImGuiColorEditFlags::NoInputs, !value); self } + /// Enables/disables the tooltip that appears when hovering the preview. #[inline] pub fn tooltip(mut self, value: bool) -> Self { self.flags.set(ImGuiColorEditFlags::NoTooltip, !value); self } + /// Enables/disables display of the inline text label (the label is in any case forwarded to + /// the tooltip and picker). #[inline] pub fn label(mut self, value: bool) -> Self { self.flags.set(ImGuiColorEditFlags::NoLabel, !value); self } + /// Enables/disables the bigger color preview on the right side of the picker. #[inline] pub fn side_preview(mut self, value: bool) -> Self { self.flags.set(ImGuiColorEditFlags::NoSidePreview, !value); self } + /// Enables/disables the vertical alpha bar/gradient in the color picker. #[inline] pub fn alpha_bar(mut self, value: bool) -> Self { self.flags.set(ImGuiColorEditFlags::AlphaBar, value); self } + /// Sets the preview style. #[inline] pub fn preview(mut self, preview: EditableColorPreview) -> Self { self.flags.set( @@ -244,21 +294,25 @@ impl<'ui, 'p> ColorPicker<'ui, 'p> { ); self } + /// Enables/disables the RGB inputs. #[inline] pub fn rgb(mut self, value: bool) -> Self { self.flags.set(ImGuiColorEditFlags::RGB, value); self } + /// Enables/disables the HSV inputs. #[inline] pub fn hsv(mut self, value: bool) -> Self { self.flags.set(ImGuiColorEditFlags::HSV, value); self } + /// Enables/disables the HEX input. #[inline] pub fn hex(mut self, value: bool) -> Self { self.flags.set(ImGuiColorEditFlags::HEX, value); self } + /// Sets the hue/saturation/value editor mode. #[inline] pub fn mode(mut self, mode: ColorPickerMode) -> Self { self.flags.set( @@ -271,6 +325,7 @@ impl<'ui, 'p> ColorPicker<'ui, 'p> { ); self } + /// Sets the formatting style of color components. #[inline] pub fn format(mut self, format: EditableColorFormat) -> Self { self.flags.set( @@ -283,11 +338,13 @@ impl<'ui, 'p> ColorPicker<'ui, 'p> { ); self } + /// Sets the shown reference color. #[inline] pub fn reference_color(mut self, ref_color: &'p [f32; 4]) -> Self { self.ref_color = Some(ref_color); self } + /// Builds the color picker. pub fn build(mut self) -> bool { if let EditableColor::Float3(_) = self.value { self.flags.insert(ImGuiColorEditFlags::NoAlpha); diff --git a/src/lib.rs b/src/lib.rs index b1f33aa..658d494 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -41,7 +41,8 @@ pub use imgui_sys::{ImDrawIdx, ImDrawVert, ImGuiColorEditFlags, ImGuiInputTextFl ImGuiSelectableFlags, ImGuiCond, ImGuiCol, ImGuiStyle, ImGuiTreeNodeFlags, ImGuiWindowFlags, ImVec2, ImVec4}; pub use child_frame::ChildFrame; -pub use color_editors::{ColorEdit, ColorEditMode, ColorPicker, EditableColor, EditableColorFormat}; +pub use color_editors::{ColorEdit, ColorEditMode, ColorPicker, ColorPickerMode, EditableColor, + EditableColorFormat, EditableColorPreview}; pub use input::{InputFloat, InputFloat2, InputFloat3, InputFloat4, InputInt, InputInt2, InputInt3, InputInt4, InputText}; pub use menus::{Menu, MenuItem}; @@ -641,6 +642,7 @@ impl<'ui> Ui<'ui> { // Widgets: Color Editor/Picker impl<'ui> Ui<'ui> { + /// Constructs a new color editor builder. pub fn color_edit<'p, V: Into>>( &self, label: &'p ImStr, @@ -657,6 +659,7 @@ impl<'ui> Ui<'ui> { pub fn color_edit4<'p>(&self, label: &'p ImStr, value: &'p mut [f32; 4]) -> ColorEdit<'ui, 'p> { self.color_edit(label, value) } + /// Constructs a new color picker builder. pub fn color_picker<'p, V: Into>>( &self, label: &'p ImStr,