---
name: "al_create_native_file_dialog"
section: "3"
platform: "linux"
package: "allegro"
version: "5.2.11.3-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/al_create_native_file_dialog"
---

# al\_create\_native\_file\_dialog(3)

Allegro 5 API

## 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(3)](/al_show_native_file_dialog/3.md) to display it, and from which you then can query the results using [al\_get\_native\_file\_dialog\_count(3)](/al_get_native_file_dialog_count/3.md) and [al\_get\_native\_file\_dialog\_path(3)](/al_get_native_file_dialog_path/3.md). When you are done, call [al\_destroy\_native\_file\_dialog(3)](/al_destroy_native_file_dialog/3.md) on it.

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