diff --git a/src/clipboard.rs b/src/clipboard.rs index 5b61380..d80027d 100644 --- a/src/clipboard.rs +++ b/src/clipboard.rs @@ -7,8 +7,12 @@ use std::ptr; use crate::string::{ImStr, ImString}; use crate::Ui; +/// Trait for clipboard backends pub trait ClipboardBackend { + /// Returns the current clipboard contents as an owned imgui-rs string, or None if the + /// clipboard is empty or inaccessible fn get(&mut self) -> Option; + /// Sets the clipboard contents to the given imgui-rs string slice. fn set(&mut self, value: &ImStr); } @@ -67,9 +71,10 @@ pub(crate) unsafe extern "C" fn set_clipboard_text(user_data: *mut c_void, text: }); } +/// # Clipboard impl<'ui> Ui<'ui> { - /// Returns the current clipboard contents as text or None if clipboard cannot be accessed or - /// it is empty + /// Returns the current clipboard contents as text, or None if the clipboard is empty or cannot + /// be accessed pub fn clipboard_text(&self) -> Option { let io = self.io(); io.get_clipboard_text_fn.and_then(|get_clipboard_text_fn| { diff --git a/src/context.rs b/src/context.rs index 48a94c0..3fe3703 100644 --- a/src/context.rs +++ b/src/context.rs @@ -101,6 +101,7 @@ impl Context { clear_current_context(); SuspendedContext(self) } + /// Returns the path to the ini file, or None if not set pub fn ini_filename(&self) -> Option<&ImStr> { let io = self.io(); if io.ini_filename.is_null() { @@ -109,6 +110,9 @@ impl Context { unsafe { Some(ImStr::from_ptr_unchecked(io.ini_filename)) } } } + /// Sets the path to the ini file (default is "imgui.ini") + /// + /// Pass None to disable automatic .Ini saving. pub fn set_ini_filename>>(&mut self, ini_filename: T) { let ini_filename = ini_filename.into(); self.io_mut().ini_filename = ini_filename @@ -117,6 +121,7 @@ impl Context { .unwrap_or(ptr::null()); self.ini_filename = ini_filename; } + /// Returns the path to the log file, or None if not set pub fn log_filename(&self) -> Option<&ImStr> { let io = self.io(); if io.log_filename.is_null() { @@ -125,6 +130,7 @@ impl Context { unsafe { Some(ImStr::from_ptr_unchecked(io.log_filename)) } } } + /// Sets the log filename (default is "imgui_log.txt"). pub fn set_log_filename>>(&mut self, log_filename: T) { let log_filename = log_filename.into(); self.io_mut().log_filename = log_filename @@ -133,6 +139,7 @@ impl Context { .unwrap_or(ptr::null()); self.log_filename = log_filename; } + /// Returns the backend platform name, or None if not set pub fn platform_name(&self) -> Option<&ImStr> { let io = self.io(); if io.backend_platform_name.is_null() { @@ -141,6 +148,7 @@ impl Context { unsafe { Some(ImStr::from_ptr_unchecked(io.backend_platform_name)) } } } + /// Sets the backend platform name pub fn set_platform_name>>(&mut self, platform_name: T) { let platform_name = platform_name.into(); self.io_mut().backend_platform_name = platform_name @@ -149,6 +157,7 @@ impl Context { .unwrap_or(ptr::null()); self.platform_name = platform_name; } + /// Returns the backend renderer name, or None if not set pub fn renderer_name(&self) -> Option<&ImStr> { let io = self.io(); if io.backend_renderer_name.is_null() { @@ -157,6 +166,7 @@ impl Context { unsafe { Some(ImStr::from_ptr_unchecked(io.backend_renderer_name)) } } } + /// Sets the backend renderer name pub fn set_renderer_name>>(&mut self, renderer_name: T) { let renderer_name = renderer_name.into(); self.io_mut().backend_renderer_name = renderer_name @@ -165,13 +175,16 @@ impl Context { .unwrap_or(ptr::null()); self.renderer_name = renderer_name; } + /// Loads settings from a string slice containing settings in .Ini file format pub fn load_ini_settings(&mut self, data: &str) { unsafe { sys::igLoadIniSettingsFromMemory(data.as_ptr() as *const _, data.len()) } } + /// Saves settings to a mutable string buffer in .Ini file format pub fn save_ini_settings(&mut self, buf: &mut String) { let data = unsafe { CStr::from_ptr(sys::igSaveIniSettingsToMemory(ptr::null_mut())) }; buf.push_str(&data.to_string_lossy()); } + /// Sets the clipboard backend used for clipboard operations pub fn set_clipboard_backend(&mut self, backend: Box) { use std::borrow::BorrowMut; let mut clipboard_ctx = Box::new(ClipboardContext::new(backend)); @@ -392,6 +405,38 @@ Collapsed=0"; assert_eq!(data.trim(), buf.trim()); } +#[test] +fn test_default_ini_filename() { + use crate::im_str; + let _guard = crate::test::TEST_MUTEX.lock(); + let ctx = Context::create(); + assert_eq!(ctx.ini_filename(), Some(im_str!("imgui.ini"))); +} + +#[test] +fn test_set_ini_filename() { + use crate::im_str; + let (_guard, mut ctx) = crate::test::test_ctx(); + ctx.set_ini_filename(Some(im_str!("test.ini").to_owned())); + assert_eq!(ctx.ini_filename(), Some(im_str!("test.ini"))); +} + +#[test] +fn test_default_log_filename() { + use crate::im_str; + let _guard = crate::test::TEST_MUTEX.lock(); + let ctx = Context::create(); + assert_eq!(ctx.log_filename(), Some(im_str!("imgui_log.txt"))); +} + +#[test] +fn test_set_log_filename() { + use crate::im_str; + let (_guard, mut ctx) = crate::test::test_ctx(); + ctx.set_log_filename(Some(im_str!("test.log").to_owned())); + assert_eq!(ctx.log_filename(), Some(im_str!("test.log"))); +} + impl Context { /// Returns an immutable reference to the inputs/outputs object pub fn io(&self) -> &Io { @@ -436,10 +481,12 @@ impl Context { }, } } + /// Starts a new frame and returns an `Ui` instance for constructing a user interface. + /// /// # Panics /// /// Panics if the context uses a shared font atlas that is already borrowed - pub fn frame<'ui, 'a: 'ui>(&'a mut self) -> Ui<'ui> { + pub fn frame(&mut self) -> Ui { // Clear default font if it no longer exists. This could be an error in the future let default_font = self.io().font_default; if !default_font.is_null() && self.fonts().get_font(FontId(default_font)).is_none() { diff --git a/src/fonts/atlas.rs b/src/fonts/atlas.rs index 16e57e4..3ad5cfb 100644 --- a/src/fonts/atlas.rs +++ b/src/fonts/atlas.rs @@ -21,6 +21,7 @@ bitflags! { } } +/// A font identifier #[derive(Copy, Clone, Debug, Eq, PartialEq)] pub struct FontId(pub(crate) *const Font); @@ -255,11 +256,12 @@ fn test_font_atlas_memory_layout() { assert_field_offset!(custom_rect_ids, CustomRectIds); } +/// A source for binary font data #[derive(Clone, Debug)] pub enum FontSource<'a> { - DefaultFontData { - config: Option, - }, + /// Default font included with the library (ProggyClean.ttf) + DefaultFontData { config: Option }, + /// Binary TTF/OTF font data TtfData { data: &'a [u8], size_pixels: f32, @@ -267,18 +269,30 @@ pub enum FontSource<'a> { }, } +/// Configuration settings for a font #[derive(Clone, Debug)] pub struct FontConfig { + /// Size in pixels for the rasterizer pub size_pixels: f32, + /// Horizontal oversampling pub oversample_h: i32, + /// Vertical oversampling pub oversample_v: i32, + /// Align every glyph to pixel boundary pub pixel_snap_h: bool, + /// Extra spacing (in pixels) between glyphs pub glyph_extra_spacing: [f32; 2], + /// Offset for all glyphs in this font pub glyph_offset: [f32; 2], + /// Unicode ranges to use from this font pub glyph_ranges: FontGlyphRanges, + /// Minimum advance_x for glyphs pub glyph_min_advance_x: f32, + /// Maximum advance_x for glyphs pub glyph_max_advance_x: f32, + /// Settings for a custom font rasterizer if used pub rasterizer_flags: u32, + /// Brighten (>1.0) or darken (<1.0) font output pub rasterizer_multiply: f32, } @@ -364,8 +378,13 @@ fn test_font_config_default() { /// Handle to a font atlas texture #[derive(Clone, Debug)] pub struct FontAtlasTexture<'a> { + /// Texture width (in pixels) pub width: u32, + /// Texture height (in pixels) pub height: u32, + /// Raw texture data (in bytes). + /// + /// The format depends on which function was called to obtain this data. pub data: &'a [u8], } diff --git a/src/fonts/font.rs b/src/fonts/font.rs index 2c90fb2..ec9fd86 100644 --- a/src/fonts/font.rs +++ b/src/fonts/font.rs @@ -5,6 +5,7 @@ use crate::fonts::glyph::FontGlyph; use crate::internal::{ImVector, RawCast}; use crate::sys; +/// Runtime data for a single font within a font atlas #[repr(C)] pub struct Font { index_advance_x: ImVector, @@ -28,6 +29,7 @@ pub struct Font { unsafe impl RawCast for Font {} impl Font { + /// Returns the identifier of this font pub fn id(&self) -> FontId { FontId(self as *const _) } diff --git a/src/fonts/glyph.rs b/src/fonts/glyph.rs index 417d386..e4da106 100644 --- a/src/fonts/glyph.rs +++ b/src/fonts/glyph.rs @@ -1,6 +1,7 @@ use crate::internal::RawCast; use crate::sys; +/// A single font glyph #[derive(Copy, Clone, Debug, PartialEq)] #[repr(C)] pub struct FontGlyph { diff --git a/src/fonts/mod.rs b/src/fonts/mod.rs index fa8cda7..0ee9f38 100644 --- a/src/fonts/mod.rs +++ b/src/fonts/mod.rs @@ -7,6 +7,7 @@ pub mod font; pub mod glyph; pub mod glyph_ranges; +/// # Fonts impl<'ui> Ui<'ui> { /// Returns the current font pub fn current_font(&self) -> &Font { @@ -22,7 +23,7 @@ impl<'ui> Ui<'ui> { pub fn font_tex_uv_white_pixel(&self) -> [f32; 2] { unsafe { sys::igGetFontTexUvWhitePixel_nonUDT2().into() } } - /// Set the font scale of the current window + /// Sets the font scale of the current window pub fn set_window_font_scale(&self, scale: f32) { unsafe { sys::igSetWindowFontScale(scale) } } diff --git a/src/input/keyboard.rs b/src/input/keyboard.rs index d781264..b3105a4 100644 --- a/src/input/keyboard.rs +++ b/src/input/keyboard.rs @@ -118,7 +118,7 @@ impl<'ui> Ui<'ui> { pub fn key_pressed_amount(&self, key_index: u32, repeat_delay: f32, rate: f32) -> u32 { unsafe { sys::igGetKeyPressedAmount(key_index as i32, repeat_delay, rate) as u32 } } - /// Focus keyboard on a widget relative to current position + /// Focuses keyboard on a widget relative to current position pub fn set_keyboard_focus_here(&self, target_widget: FocusedWidget) { unsafe { sys::igSetKeyboardFocusHere(target_widget.as_offset()); diff --git a/src/input/mouse.rs b/src/input/mouse.rs index 895d56a..721f10a 100644 --- a/src/input/mouse.rs +++ b/src/input/mouse.rs @@ -142,7 +142,7 @@ impl<'ui> Ui<'ui> { // references to it unsafe { sys::igResetMouseDragDelta(button as i32) } } - /// Get the currently desired mouse cursor type. + /// Returns the currently desired mouse cursor type. /// /// Returns `None` if no cursor should be displayed pub fn mouse_cursor(&self) -> Option { @@ -158,7 +158,7 @@ impl<'ui> Ui<'ui> { _ => None, } } - /// Set the desired mouse cursor type. + /// Sets the desired mouse cursor type. /// /// Passing `None` hides the mouse cursor. pub fn set_mouse_cursor(&self, cursor_type: Option) { diff --git a/src/internal.rs b/src/internal.rs index 88edb7c..dc2f483 100644 --- a/src/internal.rs +++ b/src/internal.rs @@ -1,5 +1,8 @@ +//! Internal raw utilities (don't use unless you know what you're doing!) + use std::slice; +/// A generic version of the raw imgui-sys ImVector struct types #[repr(C)] pub struct ImVector { size: i32, @@ -49,15 +52,19 @@ pub trait RawWrapper { /// Casting from/to a raw type that has the same layout and alignment as the target type pub unsafe trait RawCast: Sized { + /// Casts an immutable reference from the raw type unsafe fn from_raw(raw: &T) -> &Self { &*(raw as *const _ as *const Self) } + /// Casts a mutable reference from the raw type unsafe fn from_raw_mut(raw: &mut T) -> &mut Self { &mut *(raw as *mut _ as *mut Self) } + /// Casts an immutable reference to the raw type unsafe fn raw(&self) -> &T { &*(self as *const _ as *const T) } + /// Casts a mutable reference to the raw type unsafe fn raw_mut(&mut self) -> &mut T { &mut *(self as *mut _ as *mut T) } diff --git a/src/layout.rs b/src/layout.rs index 3bc9d22..3bc749e 100644 --- a/src/layout.rs +++ b/src/layout.rs @@ -42,29 +42,29 @@ impl<'ui> Ui<'ui> { pub fn spacing(&self) { unsafe { sys::igSpacing() } } - /// Fill a space of `size` in pixels with nothing on the current window. + /// Fills a space of `size` in pixels with nothing on the current window. /// /// Can be used to move the cursor on the window. pub fn dummy(&self, size: [f32; 2]) { unsafe { sys::igDummy(size.into()) } } - /// Move content position to the right by `Style::indent_spacing` + /// Moves content position to the right by `Style::indent_spacing` pub fn indent(&self) { unsafe { sys::igIndent(0.0) }; } - /// Move content position to the right by `width` + /// Moves content position to the right by `width` pub fn indent_by(&self, width: f32) { unsafe { sys::igIndent(width) }; } - /// Move content position to the left by `Style::indent_spacing` + /// Moves content position to the left by `Style::indent_spacing` pub fn unindent(&self) { unsafe { sys::igUnindent(0.0) }; } - /// Move content position to the left by `width` + /// Moves content position to the left by `width` pub fn unindent_by(&self, width: f32) { unsafe { sys::igUnindent(width) }; } - /// Group items together as a single item. + /// Groups items together as a single item. /// /// May be useful to handle the same mouse event on a group of items, for example. pub fn group(&self) -> GroupToken { @@ -75,7 +75,7 @@ impl<'ui> Ui<'ui> { pub fn cursor_pos(&self) -> [f32; 2] { unsafe { sys::igGetCursorPos_nonUDT2().into() } } - /// Set the cursor position (in window coordinates). + /// Sets the cursor position (in window coordinates). /// /// This sets the point on which the next widget will be drawn. pub fn set_cursor_pos(&self, pos: [f32; 2]) { @@ -91,11 +91,11 @@ impl<'ui> Ui<'ui> { pub fn cursor_screen_pos(&self) -> [f32; 2] { unsafe { sys::igGetCursorScreenPos_nonUDT2().into() } } - /// Set the cursor position (in absolute screen coordinates) + /// Sets the cursor position (in absolute screen coordinates) pub fn set_cursor_screen_pos(&self, pos: [f32; 2]) { unsafe { sys::igSetCursorScreenPos(pos.into()) } } - /// Vertically align text baseline so that it will align properly to regularly frame items. + /// Vertically aligns text baseline so that it will align properly to regularly frame items. /// /// Call this if you have text on a line before a framed item. pub fn align_text_to_frame_padding(&self) { diff --git a/src/lib.rs b/src/lib.rs index 7569396..faf98f7 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -99,6 +99,7 @@ impl Context { } } +/// A temporary reference for building the user interface for one frame pub struct Ui<'ui> { ctx: &'ui Context, font_atlas: Option>, @@ -111,9 +112,11 @@ fn fmt_ptr() -> *const c_char { } impl<'ui> Ui<'ui> { + /// Returns an immutable reference to the inputs/outputs object pub fn io(&self) -> &Io { unsafe { &*(sys::igGetIO() as *const Io) } } + /// Returns an immutable reference to the font atlas pub fn fonts(&self) -> FontAtlasRef { match self.font_atlas { Some(ref font_atlas) => FontAtlasRef::Shared(font_atlas), @@ -123,9 +126,14 @@ impl<'ui> Ui<'ui> { }, } } + /// Returns a clone of the user interface style pub fn clone_style(&self) -> Style { *self.ctx.style() } + /// Returns a single style color from the user interface style. + /// + /// Use this function if you need to access the colors, but don't want to clone the entire + /// style object. pub fn style_color(&self, style_color: StyleColor) -> [f32; 4] { self.ctx.style()[style_color] } @@ -135,6 +143,7 @@ impl<'ui> Ui<'ui> { pub fn frame_count(&self) -> i32 { unsafe { sys::igGetFrameCount() } } + /// Renders the frame and returns a reference to the resulting draw data pub fn render(self) -> &'ui DrawData { unsafe { sys::igRender(); diff --git a/src/render/draw_data.rs b/src/render/draw_data.rs index f124d9a..50d60f5 100644 --- a/src/render/draw_data.rs +++ b/src/render/draw_data.rs @@ -183,6 +183,7 @@ impl<'a> Iterator for DrawCmdIterator<'a> { } } +/// A vertex index pub type DrawIdx = sys::ImDrawIdx; #[derive(Copy, Clone, Debug, PartialEq)] @@ -193,6 +194,7 @@ pub struct DrawCmdParams { pub idx_offset: usize, } +/// A draw command pub enum DrawCmd { Elements { count: usize, diff --git a/src/render/renderer.rs b/src/render/renderer.rs index 246e19d..4ff5d2a 100644 --- a/src/render/renderer.rs +++ b/src/render/renderer.rs @@ -1,5 +1,6 @@ use std::collections::HashMap; +/// An opaque texture identifier #[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)] #[repr(transparent)] pub struct TextureId(usize); diff --git a/src/widget/color_editors.rs b/src/widget/color_editors.rs index af60459..433dcf9 100644 --- a/src/widget/color_editors.rs +++ b/src/widget/color_editors.rs @@ -603,9 +603,9 @@ impl<'a> ColorButton<'a> { /// # Widgets: Color Editor/Picker impl<'ui> Ui<'ui> { - /// Initialize current options (generally on application startup) if you want to select a - /// default format, picker type, etc. Users will be able to change many settings, unless you - /// use .options(false) in your widget builders. + /// Initializes current color editor/picker options (generally on application startup) if you + /// want to select a default format, picker type, etc. Users will be able to change many + /// settings, unless you use .options(false) in your widget builders. pub fn set_color_edit_options(&self, flags: ColorEditFlags) { unsafe { sys::igSetColorEditOptions(flags.bits() as i32); diff --git a/src/widget/progress_bar.rs b/src/widget/progress_bar.rs index 97567f9..a91e92b 100644 --- a/src/widget/progress_bar.rs +++ b/src/widget/progress_bar.rs @@ -54,7 +54,7 @@ impl<'a> ProgressBar<'a> { self.size = size.into(); self } - /// Builds the progress bar. + /// Builds the progress bar pub fn build(self, _: &Ui) { unsafe { sys::igProgressBar( diff --git a/src/window/content_region.rs b/src/window/content_region.rs index a5df9fa..82811da 100644 --- a/src/window/content_region.rs +++ b/src/window/content_region.rs @@ -3,7 +3,7 @@ use crate::Ui; /// # Content region impl<'ui> Ui<'ui> { - /// Returns the current content boundaries in *window coordinates* + /// Returns the current content boundaries (in *window coordinates*) pub fn content_region_max(&self) -> [f32; 2] { unsafe { sys::igGetContentRegionMax_nonUDT2().into() } } @@ -11,13 +11,13 @@ impl<'ui> Ui<'ui> { pub fn content_region_avail(&self) -> [f32; 2] { unsafe { sys::igGetContentRegionAvail_nonUDT2().into() } } - /// Content boundaries min in *window coordinates*. + /// Content boundaries min (in *window coordinates*). /// /// Roughly equal to [0.0, 0.0] - scroll. pub fn window_content_region_min(&self) -> [f32; 2] { unsafe { sys::igGetWindowContentRegionMin_nonUDT2().into() } } - /// Content boundaries max in *window coordinates*. + /// Content boundaries max (in *window coordinates*). /// /// Roughly equal to [0.0, 0.0] + size - scroll. pub fn window_content_region_max(&self) -> [f32; 2] { diff --git a/src/window/scroll.rs b/src/window/scroll.rs index 8b48157..b4f37ef 100644 --- a/src/window/scroll.rs +++ b/src/window/scroll.rs @@ -27,19 +27,19 @@ impl<'ui> Ui<'ui> { pub fn scroll_max_y(&self) -> f32 { unsafe { sys::igGetScrollMaxY() } } - /// Set the horizontal scrolling position + /// Sets the horizontal scrolling position pub fn set_scroll_x(&self, scroll_x: f32) { unsafe { sys::igSetScrollX(scroll_x) }; } - /// Set the vertical scroll position + /// Sets the vertical scroll position pub fn set_scroll_y(&self, scroll_y: f32) { unsafe { sys::igSetScrollY(scroll_y) }; } - /// Adjust vertical scroll position to make the current cursor position visible + /// Adjusts the vertical scroll position to make the current cursor position visible pub fn set_scroll_here_y(&self) { unsafe { sys::igSetScrollHereY(0.5) }; } - /// Adjust vertical scroll position to make the current cursor position visible. + /// Adjusts the vertical scroll position to make the current cursor position visible. /// /// center_y_ratio: /// @@ -49,11 +49,11 @@ impl<'ui> Ui<'ui> { pub fn set_scroll_here_y_with_ratio(&self, center_y_ratio: f32) { unsafe { sys::igSetScrollHereY(center_y_ratio) }; } - /// Adjust vertical scroll position to make the given position visible + /// Adjusts the vertical scroll position to make the given position visible pub fn set_scroll_from_pos_y(&self, local_y: f32) { unsafe { sys::igSetScrollFromPosY(local_y, 0.5) }; } - /// Adjust vertical scroll position to make the given position visible. + /// Adjusts the vertical scroll position to make the given position visible. /// /// center_y_ratio: ///