Package ej.microui.display

Class Display

  • public class Display
extends Object
    The Display object represents the pixelated screen in the platform.
    The display of the system may be retrieved by calling getDisplay().

    The display is able to render a Displayable on its implementation screen. Only one Displayable can be set on the display at a time; it is said to be visible or to be shown. The visible Displayable can be retrieved with the method getDisplayable().

    requestShow(Displayable) allows the Displayable to be selected for rendering on the display. It can be called at any time by the application, for instance in response to user inputs.

    Display uses a GraphicsContext to draw on its corresponding screen. All draw actions are serialized. The application should not use the display's graphics context outside the events mechanism requestRender() and render(). Nevertheless, for exceptional cases a new GraphicsContext may be created using getGraphicsContext(). This GraphicsContext bypasses the standard serialized drawing mechanism and allows drawings to be rendered on the display at any time.

    All events on the display are serialized: requestRender, callSerially, handleEvent etc. The display uses a FIFOPump to manage its serialized event mechanism. Some events are internally executed and some events are calling some application code.

    When a visible object has to be painted on a Display, the render method gives a GraphicsContext as argument and should use it to render the visible object.

    Direct drawing on the display can be done from application by retrieving a GraphicsContext with getGraphicsContext(). Using this mechanism does not ensure drawings will be performed before, during or after the current render(), since it bypasses the serialization system events.

    • Constructor Summary

      Constructors 
      Constructor Description
      Display()  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void callOnFlushCompleted​(Runnable run)
      Prepares a call event which will be serialized in the system event stream when the next executed flush will be done.
      void cancelCallOnFlushCompleted()
      Cancels the event previously registered by the call to callOnFlushCompleted(Runnable).
      void flush()
      Performs immediately a flush updating the display with the draw actions since the last flush if and only if the display is double buffered.
      int getBacklight()
      Returns the current backlight setting
      int getContrast()
      Returns the contrast of the display.
      static Display getDisplay()
      Returns the display of the system.
      Displayable getDisplayable()
      Returns the current Displayable object in the Display.
      The value returned by getDisplayable() may be null if no Displayable is visible.
      int getDisplayColor​(int color)
      Gets the color that will be displayed if the specified color is requested.
      For example, with a monochrome display, this method will return either 0xFFFFFF (white) or 0x000000 (black) depending on the brightness of the specified color.
      EventHandler getEventHandler()
      Returns the display's event serializer.
      GraphicsContext getGraphicsContext()
      Returns the display's GraphicsContext.
      int getHeight()
      Returns the height in pixels of the display screen area available to the application.
      int getNumberOfColors()
      Gets the number of colors that can be represented on the device.
      Note that the number of colors for a black and white display is 2.
      int getPixelDepth()
      Returns the number of bits per pixel of the display.
      int getWidth()
      Returns the width in pixels of the display screen area available to the application.
      boolean hasBacklight()
      Tells whether the display has backlight.
      boolean isColor()
      Tells whether the display offers color.
      boolean isDoubleBuffered()
      Returns if the display uses an underlying double buffer (either hardware or software).
      boolean isShown​(Displayable displayable)
      Checks whether the given displayable is visible on the display.
      void requestFlush()
      Requests a flush updating the display with the draw actions since the last flush if and only if the display is double buffered.
      void requestHide​(Displayable displayable)
      Asks to set the given displayable as hidden on the display.
      void requestRender()
      Asks to render the current displayable.
      void requestShow​(Displayable displayable)
      Asks to set the given displayable as visible on the display.
      void setBacklight​(int backlight)
      Sets the backlight of the display.
      void setContrast​(int contrast)
      Sets the contrast of the display.
      void waitFlushCompleted()
      Blocks the current thread (with all its locks) until previous call flush() has been processed.

    • Constructor Detail

      • Display

        public Display()

    • Method Detail

      • getEventHandler

        public EventHandler getEventHandler()
        Returns the display's event serializer.
        Returns:
        the display's event serializer.
        Since:
        2.0

      • getHeight

        public int getHeight()
        Returns the height in pixels of the display screen area available to the application.
        Returns:
        height of the display screen area.

      • getWidth

        public int getWidth()
        Returns the width in pixels of the display screen area available to the application.
        Returns:
        width of the display screen area.

      • getPixelDepth

        public int getPixelDepth()
        Returns the number of bits per pixel of the display.
        Returns:
        the number of bits per pixel

      • isColor

        public boolean isColor()
        Tells whether the display offers color.
        Returns:
        if display has color

      • getNumberOfColors

        public int getNumberOfColors()
        Gets the number of colors that can be represented on the device.
        Note that the number of colors for a black and white display is 2.
        Returns:
        the number of colors

      • isDoubleBuffered

        public boolean isDoubleBuffered()
        Returns if the display uses an underlying double buffer (either hardware or software). This technique is useful to avoid flickering while the user is drawing.
        Returns:
        true if and only if a double buffer is used for the display

      • getDisplayColor

        public int getDisplayColor​(int color)
        Gets the color that will be displayed if the specified color is requested.
        For example, with a monochrome display, this method will return either 0xFFFFFF (white) or 0x000000 (black) depending on the brightness of the specified color.
        Parameters:
        color - the desired color in 0x00RRGGBB format.
        Returns:
        the corresponding color that will be displayed on the graphics context (in 0x00RRGGBB format).

      • hasBacklight

        public boolean hasBacklight()
        Tells whether the display has backlight.
        Returns:
        if display has backlight

      • setContrast

        public void setContrast​(int contrast)
        Sets the contrast of the display. contrast value range is 0-100
        Parameters:
        contrast - the new value of the contrast

      • getContrast

        public int getContrast()
        Returns the contrast of the display.
        Returns:
        the current contrast of the display (range 0-100)

      • setBacklight

        public void setBacklight​(int backlight)
        Sets the backlight of the display. backlight value range is 0-100
        Parameters:
        backlight - the new value of the backlight

      • getBacklight

        public int getBacklight()
        Returns the current backlight setting
        Returns:
        the current backlight setting (range 0-100)

      • getDisplay

        public static Display getDisplay()
        Returns the display of the system. Throws a MicroUIException when there is no display.
        Returns:
        the unique display.
        Throws:
        MicroUIException - if MicroUI is not started or if there is no display.

      • getDisplayable

        @Nullable
public Displayable getDisplayable()
        Returns the current Displayable object in the Display.
        The value returned by getDisplayable() may be null if no Displayable is visible.
        Returns:
        the current Displayable object in the Display

      • getGraphicsContext

        public GraphicsContext getGraphicsContext()
        Returns the display's GraphicsContext. With this GraphicsContext, it is possible to draw on the screen at any time without following the display events serializer. The graphics context has the same dimensions as the display, which allows to modify every pixel of the display.

        If the normal system execution is repainting at the same time, the last unflushed draw actions will be visible (the previous one will be hidden by the last one). It is not possible to determine which draw action will be done last.

        This method should be only used in MicroUI.callSerially(Runnable) context to synchronize the use of this graphics context with all display events.

        Returns:
        the display's graphics context.
        See Also:
        MicroUI.callSerially(Runnable), flush()

      • requestHide

        public void requestHide​(Displayable displayable)
        Asks to set the given displayable as hidden on the display. The treatment is synchronized with the other Display events. If the Display's current displayable is this displayable, the method Displayable.onHidden() will be called.
        Parameters:
        displayable - the displayable to hide

      • isShown

        public boolean isShown​(Displayable displayable)
        Checks whether the given displayable is visible on the display.
        Parameters:
        displayable - the displayable to check
        Returns:
        true if the displayable is currently visible, false otherwise

      • requestRender

        public void requestRender()
        Asks to render the current displayable. The treatment is synchronized with the other Display events. The methods Displayable.render(GraphicsContext) and then flush() will be called when the event is executed.

        The current displayable is the displayable which is shown when the event is executed and not the displayable which is currently shown (see getDisplayable() which returns the current displayable). This displayable will be different than the displayable currently shown if the method requestShow(Displayable) is called with another displayable.

        By consequence, this method has not the same behavior than Displayable.requestRender(): this other method requests the rendering on the displayable itself (if and only if this displayable is the current displayable), and the method Displayable.render(GraphicsContext) is called if only if the displayable is the current displayable when the event is executed.

      • requestFlush

        public void requestFlush()
        Requests a flush updating the display with the draw actions since the last flush if and only if the display is double buffered. The treatment is synchronized with the other Display events. If there is already this event in Display's events queue, the new event is not added.

      • flush

        public void flush()
        Performs immediately a flush updating the display with the draw actions since the last flush if and only if the display is double buffered. The treatment is not synchronized with the other Display events; for this reason, this method should be used in MicroUI.callSerially(Runnable) context.

      • waitFlushCompleted

        public void waitFlushCompleted()
        Blocks the current thread (with all its locks) until previous call flush() has been processed.

        The following code does not block the caller (assuming there is no pending flush before calling first line): 

         display.requestFlush();
 display.waitFlushCompleted();
        because the call to display.requestFlush(); only adds the request in the event serializer: no flush is running so there is nothing to wait.

        On the other hand, the following code blocks the current thread until the call to flush() has been processed: 

         display.flush();
 display.waitFlushCompleted();
        Throws:
        MicroUIException - if the current thread is the Display's events thread.

      • callOnFlushCompleted

        public void callOnFlushCompleted​(Runnable run)
        Prepares a call event which will be serialized in the system event stream when the next executed flush will be done. This flush can already be launched or serialized (will be executed in few time) or not programmed yet.

        When the event is processed, the run() method of the Runnable object is called.
        The call to the run() method of the Runnable object is performed asynchronously. Therefore callOnFlushCompleted() will never block waiting for the run() method to finish.

        Only one event can be serialized at any time. When a new event is added while the previous one has not been executed, the new one replaces the old one. The Runnable object of the old event will not be notified about the end of next flush.

        The event can be cleared by calling cancelCallOnFlushCompleted(). In this case,The Runnable object of the event will not be notified about the end of next flush.

        The run() method should return quickly, as with other callback methods.

        Parameters:
        run - a Runnable object to call

      • cancelCallOnFlushCompleted

        public void cancelCallOnFlushCompleted()
        Cancels the event previously registered by the call to callOnFlushCompleted(Runnable). The Runnable object of the old event will not be notified about the end of next flush.