gwin_image.h

Go to the documentation of this file.

/*
 * This file is subject to the terms of the GFX License. If a copy of
 * the license was not distributed with this file, you can obtain one at:
 *
 *              http://ugfx.io/license.html
 */
 
/**
 * @file    src/gwin/gwin_image.h
 * @brief   GWIN image widget header file.
 *
 * @defgroup ImageBox ImageBox
 * @ingroup Widgets
 *
 * @brief       ImageBox widget. Used to display images within the @p GWIN widget system.
 *
 * @details     GWIN allos it to create an image widget. The widget
 *              takes no user input.
 *
 * @pre         GFX_USE_GDISP must be set to GFXON in your gfxconf.h
 * @pre         GFX_USE_GWIN must be set to GFXON in your gfxconf.h
 * @pre         GDISP_NEED_IMAGE must be set to GFXON in your gfxconf.h
 * @pre         GWIN_NEED_IMAGE must be set to GFXON in your gfxconf.h
 * @pre         At least one image type must be enabled in your gfxconf.h
 *
 * @{
 */
 
#ifndef _GWIN_IMAGE_H
#define _GWIN_IMAGE_H
 
// This file is included within "src/gwin/gwin.h"
 
// An image window
typedef struct GImageObject {
    GWindowObject   g;
    gImage          image;          // The image itself
    #if GWIN_NEED_IMAGE_ANIMATION
        GTimer          timer;      // Timer used for animated images
    #endif
} GImageObject;
 
/**
 * @brief               Create an image widget.
 * @details             Display's a picture.
 * @return              NULL if there is no resultant drawing area, otherwise the widget handle.
 *
 * @param[in] g         The GDisplay to display this window on
 * @param[in] widget    The image widget structure to initialise. If this is NULL, the structure is dynamically allocated.
 * @param[in] pInit     The initialization parameters to use.
 *
 * @note                The default background color gets set to the current default one.
 * @note                An image window knows how to redraw.
 *
 * @api
 */
GHandle gwinGImageCreate(GDisplay *g, GImageObject *widget, GWindowInit *pInit);
#define gwinImageCreate(w, pInit)           gwinGImageCreate(GDISP, w, pInit)
 
/**
 * @brief               Opens the image using a GFILE
 * @return              gTrue if the image can be opened
 *
 * @param[in] gh        The widget (must be an image widget)
 * @param[in] f         The open (for reading) GFILE to use
 *
 * @api
 */
gBool gwinImageOpenGFile(GHandle gh, GFILE *f);
 
/**
 * @brief               Opens the image using the specified filename
 * @return              gTrue if the open succeeds
 *
 * @param[in] gh        The widget (must be an image widget)
 * @param[in] filename  The filename to open
 *
 * @api
 */
#define gwinImageOpenFile(gh, filename)         gwinImageOpenGFile((gh), gfileOpen((filename), "rb"))
 
    /**
     * @brief               Sets the input routines that support reading the image from memory
     *                      in RAM or flash.
     * @pre                 GFILE_NEED_MEMFS must be GFXON
     * @return              gTrue if the IO open function succeeds
     *
     * @param[in] gh        The widget (must be an image widget)
     * @param[in] ptr       A pointer to the image in RAM or Flash
     *
     * @api
     */
#define gwinImageOpenMemory(gh, ptr)            gwinImageOpenGFile((gh), gfileOpenMemory((void *)(ptr), "rb"))
 
/**
 * @brief               Sets the input routines that support reading the image from a BaseFileStream (eg. an SD-Card).
 * @return              gTrue if the IO open function succeeds
 * @pre                 GFILE_NEED_CHIBIOSFS and GFX_USE_OS_CHIBIOS must be GFXON
 *
 * @param[in] gh        The widget (must be an image widget)
 * @param[in] streamPtr A pointer to the (open) BaseFileStream object.
 *
 * @api
 */
#define gwinImageOpenStream(gh, streamPtr)      gwinImageOpenGFile((gh), gfileOpenBaseFIleStream((streamPtr), "rb"))
 
/**
 * @brief               Cache the image.
 * @details             Decodes and caches the current frame into RAM.
 *
 * @param[in] gh        The widget (must be an image widget)
 *
 * @return              GDISP_IMAGE_ERR_OK (0) on success or an error code.
 *
 * @api
 */
gdispImageError gwinImageCache(GHandle gh);
 
#endif // _GWIN_IMAGE_H
/** @} */