Diff: GraphicsDisplay.h

Revision:

197:853d08e2fb53

Parent:

196:56820026701b

--- a/GraphicsDisplay.h	Tue Feb 11 21:26:59 2020 +0000
+++ b/GraphicsDisplay.h	Tue Feb 11 21:51:42 2020 +0000
@@ -397,6 +397,55 @@
     ///
     rect_t GetImageRect(loc_t x, loc_t y, const char * FileName = NULL);
 
+
+    /// This method gets the rectangle that would render a specified image file.
+    ///
+    /// This is the more programmer "obvious" method of getting the size of
+    /// an image file.
+    ///
+    /// @note The present implementation calls the RenderImageFile API with the
+    ///         optional getDim parameter.
+    ///
+    /// @note Not all image file formats are supported. Check the return value.
+    ///
+    /// @param[in] pt is the point defining the top-left corner.
+    /// @param[in] FileName refers to the fully qualified path and file on
+    ///     a mounted file system. The filename is optional, in which case
+    ///     it simply returns a rect_t with all elements set to zero.
+    /// @returns a rect_t that would contain the specified image. When the
+    ///     specified file cannot be found, or where this method is not yet
+    ///     supported, all elements of the returned rect_r will be zero.
+    ///
+    rect_t GetImageRect(point_t pt, const char* Filename);
+
+
+    /// This method attempts to render a specified graphics image file at
+    /// the specified screen location.
+    ///
+    /// This supports several variants of the following file types:
+    /// @li Bitmap file format,
+    /// @li Icon file format.
+    /// @li Jpeg file format.
+    ///
+    /// @note The specified image width and height, when adjusted for the
+    ///     x and y origin, must fit on the screen, or the image will not
+    ///     be shown (it does not clip the image).
+    ///
+    /// @note The file extension is tested, and if it ends in a supported
+    ///     format, the appropriate handler is called to render that image.
+    ///
+    /// @param[in] pt is the pixel coordinate of the top-left corner.
+    /// @param[in] FileName refers to the fully qualified path and file on
+    ///     a mounted file system.
+    /// @param[in] getDim when not NULL the image is not drawn. Instead, the
+    ///             getDim is filled in as the rectangle that would be drawn
+    ///             relative to the provided x,y origin. This basically
+    ///             provides a GetImageRect on a specified file.
+    /// @returns success or error code.
+    ///
+    RetCode_t RenderImageFile(point_t pt, const char* FileName, rect_t* getDim = NULL);
+
+
     /// This method attempts to render a specified graphics image file at
     /// the specified screen location.
     ///