NAME

       gfx_mode_select_filter - Even more extended version of the graphics mode selection dialog.
       Allegro game programming library.

SYNOPSIS

       #include <allegro.h>

       int gfx_mode_select_filter(int *card, int *w, int *h, int *color_depth, int (*filter)(int,
       int, int, int));

DESCRIPTION

       Even  more  extended  version  of  the  graphics  mode  selection dialog, which allows the
       programmer to customize the contents of the dialog and the user to select the color  depth
       as  well  as  the  resolution  and  hardware driver.  `filter' will be passed (card, w, h,
       color_depth) quadruplets and must return 0 to let the specified quadruplet be added to the
       list of displayed modes.

       As with gfx_mode_select, the values stored at the addresses passed to the function will be
       used as suggestions for the initial selections in the  dialog,  defaulting  to  the  first
       entry  in  each  list  if  the  values  are  not  found. Initialize the data stored at the
       addresses passed to the function to the value of 0 or -1 if you want to  ensure  that  the
       initial selection for each list will be the first entry.

       If the dialog is OK'd, it stores the selections at the addresses passed to the function.

       Example usage :

          ret = gfx_mode_select_filter(&card, &w, &h, &color_depth, user_filter);
          if (ret) {/* User okayed dialog or user_filter removed all modes */
             if (card == GFX_NONE) {
                // No modes available
                *card = 0;/* Make sure not to leave *card == GFX_NONE */
                return -1;
             }
             /* Handle changing to new mode here... */

          } else {/* User cancelled dialog or there was an error (unlikely) */
             if (card == GFX_NONE) {
                /* Error, probably out of memory */
                *card = 0;/* Make sure not to leave *card == GFX_NONE */
                return -2;
             }
             /* Carry on in current graphics mode if that is acceptable */
          }

RETURN VALUE

       Returns  zero  if  the  user  cancelled the dialog or an error occurred. In the case of an
       error then *card is assigned the value GFX_NONE. The functions return non-zero if the user
       made  a selection OR if all the modes were filtered out. In the case that all of the modes
       were filtered out, then *card is assigned the value GFX_NONE. This means  you  should  NOT
       initialize  the *card to the value of GFX_NONE, as it could interfere with determining the
       proper return value.

SEE ALSO

       gfx_mode_select(3alleg4),      gfx_mode_select_ex(3alleg4),      set_color_depth(3alleg4),
       set_gfx_mode(3alleg4), gui_fg_color(3alleg4)