In this article I'll show how to create a simple GUI application, called Cavy, to display images in PNG format using LibCapy's CapyDisplay object. The application will take a list of image's paths in argument, display them one by one, and allow to zoom in/out. The control of the application will be possible via the keyboard.

(The complete code is available at the end of the article)

First, the main function. I create the structure to manage the application, parse the arguments, init the app and run it until the user closes the window.

int main(int argc, char** argv) { ... // Create the instance of the application struct App app = { ... }; // Initialise the return code app.ret = EXIT_SUCCESS; ... // Create the argument parser and parse the arguments app.parser = CapyArgParserAlloc(argc, argv, args); ... // Initialise the appli InitApp(&app); // Run the appli RunApp(&app); ... return app.ret; }

The app structure contains the following data:

typedef struct App { // Return code at the end of execution int ret; // Arguments parser CapyArgParser* parser; // Index in the argument of the currently displayed image int16_t idxCurImg; // Size of the display CapyImgDims sizeDisplay; // Coordinates of the center of the display CapyVec2 coordCenter; // Display CapyDisplay* display; // Currently loaded image CapyImg* img; // Number of given images in argument int16_t nbImg; // Appli name char* name; // Range of acceptable values for the display size CapyRangeInt16 rangeSize; } App;

I also define a few constants and shortcut macros to make my life easier.

// Constants to control the speed of scale change and translation #define MOVE_SPEED 5.0 #define SCALE_SPEED 0.1 // Shortcut macros #define Img (app->img) #define Parser (app->parser) #define SizeDisp (&(app->sizeDisplay)) #define Disp (app->display) #define Magnifier (&(app->display->magnifier)) #define Center (&(app->coordCenter)) #define RangeSize (&(app->rangeSize))

The arguments from the command line are simple. There is the display size (optional), and everything else is considered to be a path to an image to be displayed (invalid path or image will be ignored)

// Definition of the arguments from the command line CapyArg args[] = { {.lbl=argv[0], .nbVal=capyArg_variableNbVal, .help="Display the PNG images given in argument.\n" "Non PNG images are ignored.\n" "List of commands:\n" " q: quit\n" " f: display the next image\n" " d: dislay the previous image\n" " j: zoom out\n" " k: zoom in\n" " i: reset the zoom and position\n" " cursor keys: move the image"}, {.lbl="--size", .shortLbl="-s", .nbVal=2, .help="Dimensions (width, height) of the display (in [100, 2000]). " "By default it is the size of the first loaded image"}, };

I'll use try/catch to handle exceptions. At application level there is only one exception: when the user gave no image to display in arguments.

// App exceptions enum AppExceptions { excNoImg = CapyExc_LastID, lastAppException }; // Label for the AppExceptions char* exceptionStr[] = { "No PNG images were given in argument, " "please provide at least one path to a PNG image", }; char const* ExcToStr(int16_t exc) { // If the exception ID is one of AppExceptions, // return the exception's label if (exc >= excNoImg && exc < lastAppException) return exceptionStr[exc - excNoImg]; // Else, the exception ID is not one of AppExceptions, return NULL else return NULL; }

Setting exception management in the main:

... // Set the conversion function for raised exceptions CapyAddExcToStrFun(ExcToStr); ... try { ... // Check the arguments app.nbImg = $(app.parser, getNbVal)(app.name); if (app.nbImg == 0) raiseExc(excNoImg); ... } catchDefault { // Inform the user about the raised exception $(&capyDecoratorRed, fprintf)( stdout, "Sorry, an exception occured. Exiting.\n"); $(&capyDecoratorRed, fprintf)( stdout, "%s\n", CapyExcToStr(CapyGetLastExcId())); app.ret = EXIT_FAILURE; } endCatch; ...

Initialise necessary data when instanciating the app structure.

// Create the instance of the application struct App app = { .idxCurImg = -1, .img = NULL, .name = argv[0], .display = NULL, .coordCenter = CapyVec2Create(), .ret = EXIT_SUCCESS, };

Then the app initialisation function. I load the first valid PNG image in the list of arguments, calculate the dimension of the display based on the dimension of this image and the size given in argument, and finally create the display.

// Initialisation of the application void InitApp(App* const app) { // Init the range of acceptable value for the display size app->rangeSize = CapyRangeInt16Create(100, 2000); // Load the first image LoadImg(app, 1); // If there is no valid image in the list of argument, raise an exception if (!Img) raiseExc(excNoImg); // If the user has provided the dimension of the display, // set the dimension as requested if ($(Parser, isSet)("--size")) loop (i, 2) SizeDisp->dims[i] = $(Parser, getAsInt)("--size", i); // Else, the user hasn't provided the dimension of the display, // set the dimension to the size of the first loaded image else loop (i, 2) SizeDisp->dims[i] = Img->dims[i]; // Trim the display size to acceptable ranges loop (i, 2) SizeDisp->dims[i] = $(RangeSize, trim)(SizeDisp->dims[i]); // Calculate the coordinates of the center of the screen, used as the // fixed point when scaling loop (i, 2) Center->vals[i] = ((double)(SizeDisp->dims[i])) * 0.5; // Start the display Disp = CapyDisplayAlloc(SizeDisp, app->name); $(Disp, show)(); // Set the scale of the magnifier to fit the first loaded image in the // display double ratios[2] = { ((double)(Img->width)) / ((double)(SizeDisp->width)), ((double)(Img->height)) / ((double)(SizeDisp->height))}; Magnifier->invScale = max(ratios, 2); // Copy the initial image in the display $(Disp, magnifyImg)(Img); }

The LoadImg function loads the previous/next image in the list of arguments, ignoring any invalid argument.

// Load the next/previous image // Inputs: // app: the appli // dir: if -1 load the previous image, if +1 load the next image void LoadImg( App* const app, int8_t const dir) { // Next/previous image and its index struct {CapyImg* img; int16_t idxImg;} volatiles = { .img = NULL, .idxImg = app->idxCurImg + dir }; // Loop on the arguments until we could load a previous/next image while (!(volatiles.img) && volatiles.idxImg >= 0 && volatiles.idxImg < app->nbImg) { try { char* imgPath = $(Parser, getAsStr)(app->name, volatiles.idxImg); volatiles.img = CapyImgAllocFromPNGPath(imgPath); } catchDefault { // Ignore arguments which are not valid PNG images, update the index // and keep trying volatiles.idxImg += dir; } endCatch; } // If we could load a previous/next image if (volatiles.img) { // Free the current image and replace it with the newly loaded image CapyImgFree(&Img); Img = volatiles.img; app->idxCurImg = volatiles.idxImg; } }

The main loop of the app looks for keystrokes and process them until the display is closed. As the app doesn't need to be particularly responsive, take care to sleep and do nothing if there is nothing to do (not refreshing the displayed image if not necessary).

// Main loop of the application void RunApp(App* const app) { // Wait for the display to be actually alive while (!$(Disp, isDisplayed)()); // Loop until the window is closed while ($(Disp, isDisplayed)()) { // Loop until we have processed all the next inputs from the user CapyDisplayKeyEvt evt; do { evt = $(Disp, getKeyPressed)(); switch(evt.keyval) { case GDK_KEY_f: // next image LoadImg(app, 1); break; case GDK_KEY_d: // previous image LoadImg(app, -1); break; case GDK_KEY_j: // scale down toward the center of the screen $(Magnifier, scaleDown)(SCALE_SPEED, Center); break; case GDK_KEY_k: // scale up toward the center of the screen $(Magnifier, scaleUp)(SCALE_SPEED, Center); break; case GDK_KEY_i: // reset magnifier $(Magnifier, reset)(); break; case GDK_KEY_Up: // translate the image up $(Magnifier, translate)( &(CapyVec2){ .x = 0, .y = -MOVE_SPEED * Magnifier->invScale}); break; case GDK_KEY_Down: // translate the image down $(Magnifier, translate)( &(CapyVec2){ .x = 0, .y = MOVE_SPEED * Magnifier->invScale}); break; case GDK_KEY_Right: // translate the image right $(Magnifier, translate)( &(CapyVec2){ .x = MOVE_SPEED * Magnifier->invScale, .y = 0}); break; case GDK_KEY_Left: // translate the image left $(Magnifier, translate)( &(CapyVec2){ .x = -MOVE_SPEED * Magnifier->invScale, .y = 0}); break; case GDK_KEY_q: // terminate the app $(Disp, close)(); break; default: break; } // Update the display if there has been an event if (Img && evt.keyval) $(Disp, magnifyImg)(Img); } while (evt.keyval); // Wait a little to save on resources CapySleepMs(40); } }

And that's it. The complete code:

/* Cavy - A PNG image viewer Copyright (C) 2021 Pascal Baillehache baillehache.pascal@gmail.com https://baillehachepascal.dev This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>. */ #include <LibCapy/capy.h> // Constants to control the speed of scale change and translation #define MOVE_SPEED 5.0 #define SCALE_SPEED 0.1 // Shortcut macros #define Img (app->img) #define Parser (app->parser) #define SizeDisp (&(app->sizeDisplay)) #define Disp (app->display) #define Magnifier (&(app->display->magnifier)) #define Center (&(app->coordCenter)) #define RangeSize (&(app->rangeSize)) // App exceptions enum AppExceptions { excNoImg = CapyExc_LastID, lastAppException }; // Label for the AppExceptions char* exceptionStr[] = { "No PNG images were given in argument, " "please provide at least one path to a PNG image", }; char const* ExcToStr(int16_t exc) { // If the exception ID is one of AppExceptions, // return the exception's label if (exc >= excNoImg && exc < lastAppException) return exceptionStr[exc - excNoImg]; // Else, the exception ID is not one of AppExceptions, return NULL else return NULL; } // App structure typedef struct App { // Return code at the end of execution int ret; // Arguments parser CapyArgParser* parser; // Index in the argument of the currently displayed image int16_t idxCurImg; // Size of the display CapyImgDims sizeDisplay; // Coordinates of the center of the display CapyVec2 coordCenter; // Display CapyDisplay* display; // Currently loaded image CapyImg* img; // Number of given images in argument int16_t nbImg; // Appli name char* name; // Range of acceptable values for the display size CapyRangeInt16 rangeSize; } App; // Load the next/previous image // Inputs: // app: the appli // dir: if -1 load the previous image, if +1 load the next image void LoadImg( App* const app, int8_t const dir) { // Next/previous image and its index struct {CapyImg* img; int16_t idxImg;} volatiles = { .img = NULL, .idxImg = app->idxCurImg + dir }; // Loop on the arguments until we could load a previous/next image while (!(volatiles.img) && volatiles.idxImg >= 0 && volatiles.idxImg < app->nbImg) { try { char* imgPath = $(Parser, getAsStr)(app->name, volatiles.idxImg); volatiles.img = CapyImgAllocFromPNGPath(imgPath); } catchDefault { // Ignore arguments which are not valid PNG images, update the index // and keep trying volatiles.idxImg += dir; } endCatch; } // If we could load a previous/next image if (volatiles.img) { // Free the current image and replace it with the newly loaded image CapyImgFree(&Img); Img = volatiles.img; app->idxCurImg = volatiles.idxImg; } } // Initialisation of the application void InitApp(App* const app) { // Init the range of acceptable value for the display size app->rangeSize = CapyRangeInt16Create(100, 2000); // Load the first image LoadImg(app, 1); // If there is no valid image in the list of argument, raise an exception if (!Img) raiseExc(excNoImg); // If the user has provided the dimension of the display, // set the dimension as requested if ($(Parser, isSet)("--size")) loop (i, 2) SizeDisp->dims[i] = $(Parser, getAsInt)("--size", i); // Else, the user hasn't provided the dimension of the display, // set the dimension to the size of the first loaded image else loop (i, 2) SizeDisp->dims[i] = Img->dims[i]; // Trim the display size to acceptable ranges loop (i, 2) SizeDisp->dims[i] = $(RangeSize, trim)(SizeDisp->dims[i]); // Calculate the coordinates of the center of the screen, used as the // fixed point when scaling loop (i, 2) Center->vals[i] = ((double)(SizeDisp->dims[i])) * 0.5; // Start the display Disp = CapyDisplayAlloc(SizeDisp, app->name); $(Disp, show)(); // Set the scale of the magnifier to fit the first loaded image in the // display double ratios[2] = { ((double)(Img->width)) / ((double)(SizeDisp->width)), ((double)(Img->height)) / ((double)(SizeDisp->height))}; Magnifier->invScale = max(ratios, 2); // Copy the initial image in the display $(Disp, magnifyImg)(Img); } // Main loop of the application void RunApp(App* const app) { // Wait for the display to be actually alive while (!$(Disp, isDisplayed)()); // Loop until the window is closed while ($(Disp, isDisplayed)()) { // Loop until we have processed all the next inputs from the user CapyDisplayKeyEvt evt; do { evt = $(Disp, getKeyPressed)(); switch(evt.keyval) { case GDK_KEY_f: // next image LoadImg(app, 1); break; case GDK_KEY_d: // previous image LoadImg(app, -1); break; case GDK_KEY_j: // scale down toward the center of the screen $(Magnifier, scaleDown)(SCALE_SPEED, Center); break; case GDK_KEY_k: // scale up toward the center of the screen $(Magnifier, scaleUp)(SCALE_SPEED, Center); break; case GDK_KEY_i: // reset magnifier $(Magnifier, reset)(); break; case GDK_KEY_Up: // translate the image up $(Magnifier, translate)( &(CapyVec2){ .x = 0, .y = -MOVE_SPEED * Magnifier->invScale}); break; case GDK_KEY_Down: // translate the image down $(Magnifier, translate)( &(CapyVec2){ .x = 0, .y = MOVE_SPEED * Magnifier->invScale}); break; case GDK_KEY_Right: // translate the image right $(Magnifier, translate)( &(CapyVec2){ .x = MOVE_SPEED * Magnifier->invScale, .y = 0}); break; case GDK_KEY_Left: // translate the image left $(Magnifier, translate)( &(CapyVec2){ .x = -MOVE_SPEED * Magnifier->invScale, .y = 0}); break; case GDK_KEY_q: // terminate the app $(Disp, close)(); break; default: break; } // Update the display if there has been an event if (Img && evt.keyval) $(Disp, magnifyImg)(Img); } while (evt.keyval); // Wait a little to save on resources CapySleepMs(40); } } // Main function int main( int argc, char** argv) { // Set the conversion function for raised exceptions CapyAddExcToStrFun(ExcToStr); // Create the instance of the application struct App app = { .idxCurImg = -1, .img = NULL, .name = argv[0], .display = NULL, .coordCenter = CapyVec2Create(), .ret = EXIT_SUCCESS, }; try { // Definition of the arguments from the command line CapyArg args[] = { {.lbl=argv[0], .nbVal=capyArg_variableNbVal, .help="Display the PNG images given in argument.\n" "Non PNG images are ignored.\n" "List of commands:\n" " q: quit\n" " f: display the next image\n" " d: dislay the previous image\n" " j: zoom out\n" " k: zoom in\n" " i: reset the zoom and position\n" " cursor keys: move the image"}, {.lbl="--size", .shortLbl="-s", .nbVal=2, .help="Dimensions (width, height) of the display (in [100, 2000]). " "By default it is the size of the first loaded image"}, }; // Create the argument parser and parse the arguments app.parser = CapyArgParserAlloc(argc, argv, args); // Check the arguments app.nbImg = $(app.parser, getNbVal)(app.name); if (app.nbImg == 0) raiseExc(excNoImg); // Initialise the appli InitApp(&app); // Run the appli RunApp(&app); } catchDefault { // Inform the user about the raised exception $(&capyDecoratorRed, fprintf)( stdout, "Sorry, an exception occured. Exiting.\n"); $(&capyDecoratorRed, fprintf)( stdout, "%s\n", CapyExcToStr(CapyGetLastExcId())); app.ret = EXIT_FAILURE; } endCatch; return app.ret; }

Compile with the following Makefile:

CAPY_PARAM=-std=c18 -I./ -Wall -Wextra -Wshadow -Wno-format-truncation -Werror -Wfatal-errors -O3 -ggdb -fopenmp -DPNG_SKIP_SETJMP_CHECK `pkg-config --cflags gtk+-3.0` -D_XOPEN_SOURCE=700 -DCAPY_WITH_GUI=1 CAPY_LINK=-lcapy -lm -fopenmp -lpng `pkg-config --libs gtk+-3.0` cavy: main.o Makefile gcc -o cavy main.o $(CAPY_LINK) main.o: main.c Makefile gcc -c main.c $(CAPY_PARAM)