Remove DisplayMode (#119)

* Add release method

This enabled reclaiming gpios which may be necessary for some hardware configurations to enter low power mode

* Remove DisplayMode

* Remove some unnecessary trait bounds

* Move reset method as it doesn't need WriteOnlyDataCommand

* Add DisplayModeTrait to prelude

* Doc link fixes

* Run cargo fmt

* Fix links

* Add CHANGELOG entry

* More link fixes

* Word wrapping fix

* Change back to standard relative links

* Fix missed link

* Update CHANGELOG.md

Co-authored-by: James Waples <[email protected]>

Co-authored-by: Dániel Buga <[email protected]>
Co-authored-by: James Waples <[email protected]>

Author: 3 people

CHANGELOG.md

@@ -8,6 +8,7 @@
 
 ### Changed
 
+-**(breaking)** [#119](https://github.com/jamwaffles/ssd1306/pull/119) Remove `DisplayMode` and `RawMode`
 - [#120](https://github.com/jamwaffles/ssd1306/pull/120) Update to v0.4 [`display-interface`](https://crates.io/crates/display-interface)
 - **(breaking)** [#116](https://github.com/jamwaffles/ssd1306/pull/116) Replace custom I2C and SPI interfaces by generic [`display-interface`](https://crates.io/crates/display-interface)
 - **(breaking)** [#113](https://github.com/jamwaffles/ssd1306/pull/113) Removed public `send_bounded_data` from DisplayInterface and implementations

src/builder.rs

@@ -1,16 +1,13 @@
 //! Interface factory
 //!
-//! This is the easiest way to create a driver instance, with the ability to set various parameters of the driver.
+//! This is the easiest way to create a driver instance, with the ability to set various parameters
+//! of the driver.
 //!
 //! To finish the builder and produce a connected display interface, call `.connect(interface)`
 //! where `interface` is an instantiated `DisplayInterface` implementation. For I2C interfaces
 //! there's also an [`I2CDIBuilder`] to simplify the construction of an I2C `DisplayInterface`. The
-//! builder will be consumed into a [`mode::RawMode`] object which can be coerced into a richer
-//! display mode like [`mode::Graphics`].
-//!
-//! [`I2CDIBuilder`]: ./struct.I2CDIBuilder.html
-//! [`mode::RawMode`]: ../mode/raw/struct.RawMode.html
-//! [`mode::Graphics`]: ../mode/graphics/struct.GraphicsMode.html
+//! builder will be consumed into a [`DisplayProperties`] object which can be coerced into a richer
+//! display mode like [`GraphicsMode`] or [`TerminalMode`].
 //!
 //! # Examples
 //!
@@ -40,9 +37,9 @@
 //!     .connect(interface);
 //! ```
 //!
-//! The above examples will produce a [RawMode](../mode/raw/struct.RawMode.html) instance
+//! The above examples will produce a [`DisplayProperties`] instance
 //! by default. You need to coerce them into a mode by specifying a type on assignment. For
-//! example, to use [`TerminalMode` mode](../mode/terminal/struct.TerminalMode.html):
+//! example, to use [`TerminalMode`] mode:
 //!
 //! ```rust
 //! # use ssd1306::test_helpers::{PinStub, SpiStub};
@@ -53,14 +50,16 @@
 //! let interface = display_interface_spi::SPIInterfaceNoCS::new(spi, dc);
 //! let display: TerminalMode<_> = Builder::new().connect(interface).into();
 //! ```
+//!
+//! [`I2CDIBuilder`]: ./struct.I2CDIBuilder.html
+//! [`DisplayProperties`]: ../properties/struct.DisplayProperties.html
+//! [`GraphicsMode`]: ../mode/graphics/struct.GraphicsMode.html
+//! [`TerminalMode`]: ../mode/terminal/struct.TerminalMode.html
 
 use display_interface::WriteOnlyDataCommand;
 
 use crate::{
-    displayrotation::DisplayRotation,
-    displaysize::DisplaySize,
-    mode::{displaymode::DisplayMode, raw::RawMode},
-    properties::DisplayProperties,
+    displayrotation::DisplayRotation, displaysize::DisplaySize, properties::DisplayProperties,
 };
 
 /// Builder struct. Driver options and interface are set using its methods.
@@ -103,12 +102,11 @@ impl Builder {
     /// Finish the builder and use some interface communicate with the display
     ///
     /// This method consumes the builder and must come last in the method call chain
-    pub fn connect<I>(self, interface: I) -> DisplayMode<RawMode<I>>
+    pub fn connect<I>(self, interface: I) -> DisplayProperties<I>
     where
         I: WriteOnlyDataCommand,
     {
-        let properties = DisplayProperties::new(interface, self.display_size, self.rotation);
-        DisplayMode::<RawMode<I>>::new(properties)
+        DisplayProperties::new(interface, self.display_size, self.rotation)
     }
 }
 

src/lib.rs

@@ -2,10 +2,10 @@
 //!
 //! The driver must be initialised by passing an I2C or SPI interface peripheral to the [`Builder`],
 //! which will in turn create a driver instance in a particular mode. By default, the builder
-//! returns a [`RawMode`] instance which isn't very useful by itself. You can coerce the driver
-//! into a more useful mode by calling `into()` and defining the type you want to coerce to. For
-//! example, to initialise the display with an I2C interface and [`GraphicsMode`], you would do
-//! something like this:
+//! returns a [`DisplayProperties`] instance which is a low level interface to manipulate the
+//! display properties (e.g. rotation). The driver can be coerced into a more useful mode by calling
+//! `into()` and defining the type you want to coerce to. For example, to initialise the display
+//! with an I2C interface and [`GraphicsMode`], you would do something like this:
 //!
 //! ```rust
 //! # use ssd1306::test_helpers::I2cStub as I2cInterface;
@@ -22,7 +22,7 @@
 //! ```
 //!
 //! See the [example](https://github.com/jamwaffles/ssd1306/blob/master/examples/graphics_i2c.rs)
-//! for more usage. The [entire `embedded_graphics` featureset](https://github.com/jamwaffles/embedded-graphics#features)
+//! for more usage. The entire `embedded_graphics` [featureset]
 //! is supported by this driver.
 //!
 //! There is also [`TerminalMode`] which allows drawing of characters to the display without
@@ -113,10 +113,11 @@
 //! disp.flush().unwrap();
 //! ```
 //!
+//! [featureset]: https://github.com/jamwaffles/embedded-graphics#features
 //! [`Builder`]: ./builder/struct.Builder.html
+//! [`DisplayProperties`]: ./properties/struct.DisplayProperties.html
 //! [`GraphicsMode`]: ./mode/graphics/struct.GraphicsMode.html
 //! [`TerminalMode`]: ./mode/terminal/struct.TerminalMode.html
-//! [`RawMode`]: ./mode/raw/struct.RawMode.html
 
 #![no_std]
 // #![deny(missing_debug_implementations)]

src/mode/displaymode.rs

@@ -1,12 +1,7 @@
 //! Abstraction of different operating modes for the SSD1306
 
-use display_interface::WriteOnlyDataCommand;
-
 use crate::properties::DisplayProperties;
 
-/// Display mode abstraction
-pub struct DisplayMode<MODE>(pub MODE);
-
 /// Trait with core functionality for display mode switching
 pub trait DisplayModeTrait<DI> {
     /// Allocate all required data and initialise display for mode
@@ -15,25 +10,3 @@ pub trait DisplayModeTrait<DI> {
     /// Release resources for reuse with different mode
     fn release(self) -> DisplayProperties<DI>;
 }
-
-impl<MODE> DisplayMode<MODE> {
-    /// Setup display to run in requested mode
-    pub fn new<DI>(properties: DisplayProperties<DI>) -> Self
-    where
-        DI: WriteOnlyDataCommand,
-        MODE: DisplayModeTrait<DI>,
-    {
-        DisplayMode(MODE::new(properties))
-    }
-
-    /// Change into any mode implementing DisplayModeTrait
-    // TODO: Figure out how to stay as generic DisplayMode but act as particular mode
-    pub fn into<DI, NMODE: DisplayModeTrait<DI>>(self) -> NMODE
-    where
-        DI: WriteOnlyDataCommand,
-        MODE: DisplayModeTrait<DI>,
-    {
-        let properties = self.0.release();
-        NMODE::new(properties)
-    }
-}

src/mode/graphics.rs

@@ -65,10 +65,7 @@ use crate::{
 
 // TODO: Add to prelude
 /// Graphics mode handler
-pub struct GraphicsMode<DI>
-where
-    DI: WriteOnlyDataCommand,
-{
+pub struct GraphicsMode<DI> {
     properties: DisplayProperties<DI>,
     buffer: [u8; 1024],
     min_x: u8,
@@ -77,10 +74,7 @@ where
     max_y: u8,
 }
 
-impl<DI> DisplayModeTrait<DI> for GraphicsMode<DI>
-where
-    DI: WriteOnlyDataCommand,
-{
+impl<DI> DisplayModeTrait<DI> for GraphicsMode<DI> {
     /// Create new GraphicsMode instance
     fn new(properties: DisplayProperties<DI>) -> Self {
         GraphicsMode {
@@ -99,21 +93,7 @@ where
     }
 }
 
-impl<DI> GraphicsMode<DI>
-where
-    DI: WriteOnlyDataCommand,
-{
-    /// Clear the display buffer. You need to call `disp.flush()` for any effect on the screen
-    pub fn clear(&mut self) {
-        self.buffer = [0; 1024];
-
-        let (width, height) = self.get_dimensions();
-        self.min_x = 0;
-        self.max_x = width - 1;
-        self.min_y = 0;
-        self.max_y = height - 1;
-    }
-
+impl<DI> GraphicsMode<DI> {
     /// Reset display
     // TODO: Move to a more appropriate place
     pub fn reset<RST, DELAY, PinE>(
@@ -131,6 +111,22 @@ where
         delay.delay_ms(10);
         rst.set_high().map_err(Error::Pin)
     }
+}
+
+impl<DI> GraphicsMode<DI>
+where
+    DI: WriteOnlyDataCommand,
+{
+    /// Clear the display buffer. You need to call `disp.flush()` for any effect on the screen
+    pub fn clear(&mut self) {
+        self.buffer = [0; 1024];
+
+        let (width, height) = self.get_dimensions();
+        self.min_x = 0;
+        self.max_x = width - 1;
+        self.min_y = 0;
+        self.max_y = height - 1;
+    }
 
     /// Write out data to a display.
     ///

src/mode/mod.rs

@@ -5,7 +5,6 @@
 
 pub mod displaymode;
 pub mod graphics;
-pub mod raw;
 pub mod terminal;
 
-pub use self::{graphics::GraphicsMode, raw::RawMode, terminal::TerminalMode};
+pub use self::{graphics::GraphicsMode, terminal::TerminalMode};

src/mode/raw.rs

@@ -64,7 +64,8 @@ impl Cursor {
     }
 
     /// Advances the logical cursor by one character.
-    /// Returns a value indicating if this caused the cursor to wrap to the next line or the next screen.
+    /// Returns a value indicating if this caused the cursor to wrap to the next line or the next
+    /// screen.
     pub fn advance(&mut self) -> Option<CursorWrapEvent> {
         self.col = (self.col + 1) % self.width;
         if self.col == 0 {
@@ -158,6 +159,25 @@ where
     }
 }
 
+impl<DI> TerminalMode<DI> {
+    /// Reset display
+    pub fn reset<RST, DELAY, PinE>(
+        &mut self,
+        rst: &mut RST,
+        delay: &mut DELAY,
+    ) -> Result<(), Error<(), PinE>>
+    where
+        RST: OutputPin<Error = PinE>,
+        DELAY: DelayMs<u8>,
+    {
+        rst.set_high().map_err(Error::Pin)?;
+        delay.delay_ms(1);
+        rst.set_low().map_err(Error::Pin)?;
+        delay.delay_ms(10);
+        rst.set_high().map_err(Error::Pin)
+    }
+}
+
 impl<DI> TerminalMode<DI>
 where
     DI: WriteOnlyDataCommand,
@@ -204,23 +224,6 @@ where
         Ok(())
     }
 
-    /// Reset display
-    pub fn reset<RST, DELAY, PinE>(
-        &mut self,
-        rst: &mut RST,
-        delay: &mut DELAY,
-    ) -> Result<(), Error<(), PinE>>
-    where
-        RST: OutputPin<Error = PinE>,
-        DELAY: DelayMs<u8>,
-    {
-        rst.set_high().map_err(Error::Pin)?;
-        delay.delay_ms(1);
-        rst.set_low().map_err(Error::Pin)?;
-        delay.delay_ms(10);
-        rst.set_high().map_err(Error::Pin)
-    }
-
     /// Write out data to display. This is a noop in terminal mode.
     pub fn flush(&mut self) -> Result<(), TerminalModeError> {
         Ok(())

src/mode/terminal.rs

@@ -7,5 +7,5 @@ pub use display_interface_spi::{SPIInterface, SPIInterfaceNoCS};
 pub use super::{
     displayrotation::DisplayRotation,
     displaysize::DisplaySize,
-    mode::{GraphicsMode, TerminalMode},
+    mode::{displaymode::DisplayModeTrait, GraphicsMode, TerminalMode},
 };

src/prelude.rs

@@ -1,5 +1,6 @@
 //! Container to store and set display properties
 
+use crate::mode::displaymode::DisplayModeTrait;
 use crate::{
     command::{AddrMode, Command, VcomhLevel},
     displayrotation::DisplayRotation,
@@ -43,6 +44,11 @@ where
         }
     }
 
+    /// Releases the display interface
+    pub fn release(self) -> DI {
+        self.iface
+    }
+
     /// Initialise the display in column mode (i.e. a byte walks down a column of 8 pixels) with
     /// column 0 on the left and column _(display_width - 1)_ on the right.
     pub fn init_column_mode(&mut self) -> Result<(), DisplayError> {
@@ -242,4 +248,12 @@ where
     pub fn display_on(&mut self, on: bool) -> Result<(), DisplayError> {
         Command::DisplayOn(on).send(&mut self.iface)
     }
+
+    /// Change into any mode implementing DisplayModeTrait
+    pub fn into<NMODE: DisplayModeTrait<DI>>(self) -> NMODE
+    where
+        DI: WriteOnlyDataCommand,
+    {
+        NMODE::new(self)
+    }
 }