NAME

       al_create_native_file_dialog - Allegro 5 API

SYNOPSIS

              #include <allegro5/allegro_native_dialog.h>

              ALLEGRO_FILECHOOSER *al_create_native_file_dialog(
                 char const *initial_path,
                 char const *title,
                 char const *patterns,
                 int mode)

DESCRIPTION

       Creates a new native file dialog.  You should only have one such dialog opened at a time.

       Parameters:

       • initial_path:  The initial search path and filename.  Can be NULL.  To start with a blank file name the
         string should end with a directory separator (this should be the common case).

       • title: Title of the dialog.

       • patterns: A string containing newline separated sets of patterns to  match.   A  pattern  is  either  a
         shell-style  glob  pattern (e.g. "*.txt") or a MIME type (e.g. "image/png").  Not all platforms support
         both (and some don’t even support globs), so a portable solution is to specify a MIME type  and  simple
         style   globs   which   Allegro   will   pick  from  to  match  what  the  platform  supports  (e.g. do
         "image/png;*.png").  Multiple patterns are separated using a  semicolon.   If  the  platform  does  not
         provide support for patterns, this parameter is ignored.  Here are some example patterns:

         • "*.txt" – defines a single filter, matching *.txt files.

         • "*.txt;*.md" – like above, but matching two types of files.

         • "Text files (*.txt, *.md) *.txt;*.md" – like above, but with a custom description (separated from the
           patterns using a space).

         • "Text  files *.txt\nPNG images image/png;*.png" – defines two filters, with the second filter using a
           MIME type and extension at the same time.

           Note: Windows does not support MIME types.  Android  supports  only  MIME  types.   Instead  of  file
           patterns,  MacOS  supports  extensions, so matching based on filename beyond file type does not work.
           Allegro will parse your file pattern to try to extract the file extension.  MacOS also supports  MIME
           types,  which  behave  more  predictably.   MacOS  does not support detailed descriptions or multiple
           pattern sets, Allegro will strip the detailed descriptions and  concatenate  all  patterns  into  one
           list.

       • mode: 0, or a combination of the following flags:

       ALLEGRO_FILECHOOSER_FILE_MUST_EXIST
         If  supported by the native dialog, it will not allow entering new names, but just allow existing files
         to be selected.  Else it is ignored.

       ALLEGRO_FILECHOOSER_SAVE
         If the native dialog system has a different dialog for saving (for example one  which  allows  creating
         new directories), it is used.  Else it is ignored.

       ALLEGRO_FILECHOOSER_FOLDER
         If there is support for a separate dialog to select a folder instead of a file, it will be used.

       ALLEGRO_FILECHOOSER_PICTURES
         If a different dialog is available for selecting pictures, it is used.  Else it is ignored.

       ALLEGRO_FILECHOOSER_SHOW_HIDDEN
         If the platform supports it, also hidden files will be shown.

       ALLEGRO_FILECHOOSER_MULTIPLE
         If supported, allow selecting multiple files.

       Returns:

       A  handle to the dialog which you can pass to al_show_native_file_dialog(3alleg5) to display it, and from
       which   you   then   can   query   the   results   using   al_get_native_file_dialog_count(3alleg5)   and
       al_get_native_file_dialog_path(3alleg5).   When you are done, call al_destroy_native_file_dialog(3alleg5)
       on it.

       If a dialog window could not be created then this function returns NULL.

Allegro reference manual                                                   al_create_native_file_dialog(3alleg5)