diff --git a/README.rst b/README.rst index ffb4d81..4647b3e 100644 --- a/README.rst +++ b/README.rst @@ -113,16 +113,6 @@ Contributing Contributions are welcome! Please read our `Code of Conduct `_ before contributing to help this project stay welcoming. -Installation -============ - -This library is **NOT** built into CircuitPython to make it easy to update. To -install it either follow the directions below or :ref:`install the library bundle `. - -To install: - -#. Download and unzip the `latest release zip `_. -#. Copy the unzipped ``adafruit_character_lcd`` to the ``lib`` directory on the ``CIRCUITPY`` or ``MICROPYTHON`` drive. Building locally ================ diff --git a/adafruit_character_lcd/character_lcd.py b/adafruit_character_lcd/character_lcd.py index 80b20dc..2e16cfd 100755 --- a/adafruit_character_lcd/character_lcd.py +++ b/adafruit_character_lcd/character_lcd.py @@ -169,6 +169,11 @@ def __init__(self, rs, en, d4, d5, d6, d7, columns, lines self._message = None self._enable = None self._direction = None + # track row and column used in cursor_position + # initialize to 0,0 + self.row = 0 + self.column = 0 + self._column_align = False # pylint: enable-msg=too-many-arguments def home(self): @@ -198,6 +203,20 @@ def clear(self): self._write8(_LCD_CLEARDISPLAY) time.sleep(0.003) + @property + def column_align(self): + """If True, message text after '\\n' starts directly below start of first + character in message. If False, text after '\\n' starts at column zero. + """ + return self._column_align + + @column_align.setter + def column_align(self, enable): + if isinstance(enable, bool): + self._column_align = enable + else: + raise ValueError('The column_align value must be either True or False') + @property def cursor(self): """True if cursor is visible. False to stop displaying the cursor. @@ -230,7 +249,8 @@ def cursor(self, show): self._write8(_LCD_DISPLAYCONTROL | self.displaycontrol) def cursor_position(self, column, row): - """Move the cursor to position ``column``, ``row`` + """Move the cursor to position ``column``, ``row`` for the next + message only. Displaying a message resets the cursor position to (0, 0). :param column: column location :param row: row location @@ -243,6 +263,9 @@ def cursor_position(self, column, row): column = self.columns - 1 # Set location self._write8(_LCD_SETDDRAMADDR | (column + _LCD_ROW_OFFSETS[row])) + # Update self.row and self.column to match setter + self.row = row + self.column = column @property def blink(self): @@ -310,6 +333,11 @@ def display(self, enable): @property def message(self): """Display a string of text on the character LCD. + Start position is (0,0) if cursor_position is not set. + If cursor_position is set, message starts at the set + position from the left for left to right text and from + the right for right to left text. Resets cursor column + and row to (0,0) after displaying the message. The following example displays, "Hello, world!" on the LCD. @@ -331,28 +359,45 @@ def message(self): @message.setter def message(self, message): self._message = message - line = 0 + # Set line to match self.row from cursor_position() + line = self.row # Track times through iteration, to act on the initial character of the message initial_character = 0 # iterate through each character for character in message: # If this is the first character in the string: if initial_character == 0: - # Start at (1, 1) unless direction is set right to left, in which case start - # on the opposite side of the display. - col = 0 if self.displaymode & _LCD_ENTRYLEFT > 0 else self.columns - 1 + # Start at (0, 0) unless direction is set right to left, in which case start + # on the opposite side of the display if cursor_position not set or (0,0) + # If cursor_position is set then starts at the specified location for + # LEFT_TO_RIGHT. If RIGHT_TO_LEFT cursor_position is determined from right. + # allows for cursor_position to work in RIGHT_TO_LEFT mode + if self.displaymode & _LCD_ENTRYLEFT > 0: + col = self.column + else: + col = self.columns - 1 - self.column self.cursor_position(col, line) initial_character += 1 # If character is \n, go to next line if character == '\n': line += 1 - # Start the second line at (1, 1) unless direction is set right to left in which - # case start on the opposite side of the display. - col = 0 if self.displaymode & _LCD_ENTRYLEFT > 0 else self.columns - 1 + # Start the second line at (0, 1) unless direction is set right to left in + # which case start on the opposite side of the display if cursor_position + # is (0,0) or not set. Start second line at same column as first line when + # cursor_position is set + if self.displaymode & _LCD_ENTRYLEFT > 0: + col = self.column * self._column_align + else: + if self._column_align: + col = self.column + else: + col = self.columns - 1 self.cursor_position(col, line) # Write string to display else: self._write8(ord(character), True) + # reset column and row to (0,0) after message is displayed + self.column, self.row = 0, 0 def move_left(self): """Moves displayed text left one column.