' The MIT License (MIT)
'
' Copyright (C) 2026 Scott Duensing
'
' Permission is hereby granted, free of charge, to any person obtaining a copy
' of this software and associated documentation files (the "Software"), to
' deal in the Software without restriction, including without limitation the
' rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
' sell copies of the Software, and to permit persons to whom the Software is
' furnished to do so, subject to the following conditions:
'
' The above copyright notice and this permission notice shall be included in
' all copies or substantial portions of the Software.
'
' THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
' IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
' FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
' AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
' LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
' FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
' IN THE SOFTWARE.

' commdlg.bas -- Common Dialog Library for DVX BASIC
'
' Provides file dialogs, input dialogs, and other common UI dialogs.
' Wrappers handle the AppContextT parameter internally so BASIC
' programs just pass the visible arguments.
'
' Usage: Add this file to your project.

DECLARE LIBRARY "basrt"
    ' Show a file Open dialog. Returns selected path, or "" if cancelled.
    ' filter$ specifies file type filters, pipe-delimited:
    '   "Label (pattern)|Label (pattern)|..."
    ' The pattern is extracted from inside the parentheses.
    ' Examples:
    '   "*.txt"                                         (single pattern, legacy)
    '   "Text Files (*.txt)|All Files (*.*)"            (two filters)
    '   "Images (*.bmp;*.png;*.jpg)|All Files (*.*)"    (multi-extension)
    DECLARE FUNCTION basFileOpen(BYVAL title AS STRING, BYVAL filter AS STRING) AS STRING

    ' Show a file Save dialog. Returns selected path, or "" if cancelled.
    ' filter$ uses the same format as basFileOpen.
    DECLARE FUNCTION basFileSave(BYVAL title AS STRING, BYVAL filter AS STRING) AS STRING

    ' Show a modal text input box. Returns entered text, or "" if cancelled.
    DECLARE FUNCTION basInputBox2(BYVAL title AS STRING, BYVAL prompt AS STRING, BYVAL defaultText AS STRING) AS STRING

    ' Returns True if the most recent basInputBox2 call was cancelled,
    ' False if the user clicked OK (even with an empty field).
    DECLARE FUNCTION basInputCancelled() AS INTEGER

    ' Show a choice dialog with a listbox. items$ is pipe-delimited
    ' (e.g. "Red|Green|Blue"). Returns chosen index (0-based), or -1.
    DECLARE FUNCTION basChoiceDialog(BYVAL title AS STRING, BYVAL prompt AS STRING, BYVAL items AS STRING, BYVAL defaultIdx AS INTEGER) AS INTEGER

    ' Show a modal integer input box with spinner. Returns the entered value.
    DECLARE FUNCTION basIntInput(BYVAL title AS STRING, BYVAL prompt AS STRING, BYVAL defaultVal AS INTEGER, BYVAL minVal AS INTEGER, BYVAL maxVal AS INTEGER) AS INTEGER

    ' Show a "Save changes?" prompt with Yes/No/Cancel buttons.
    DECLARE FUNCTION basPromptSave(BYVAL title AS STRING) AS INTEGER
END DECLARE

' Return value constants for basPromptSave
CONST DVX_SAVE_YES    = 1
CONST DVX_SAVE_NO     = 2
CONST DVX_SAVE_CANCEL = 3
