nativefiledialog extended

ขยายกล่องโต้ตอบไฟล์ดั้งเดิม

ไลบรารี C ขนาดเล็กที่เปิดไฟล์ Native Filem, Folder Select และ File Save Dialogs เขียนรหัสโต้ตอบหนึ่งครั้งและให้มันปรากฏขึ้นในกล่องโต้ตอบดั้งเดิมบนแพลตฟอร์มที่รองรับทั้งหมด หลีกเลี่ยงการเชื่อมโยงการพึ่งพาขนาดใหญ่เช่น wxWidgets และ qt

ห้องสมุดนี้ใช้กล่องโต้ตอบไฟล์เนทีฟของ Michael Labbe (MLABBE/NativeFileDialog)

คุณสมบัติ:

• LEAN C API, Library Static - ไม่จำเป็นต้องใช้รันไทม์ C ++/OBJC
• รองรับ Windows (MSVC, MingW, Clang), MacOS (Clang) และ Linux (GTK, พอร์ทัล) (GCC, Clang)
• zlib ได้รับใบอนุญาต
• ชื่อที่เป็นมิตรสำหรับตัวกรอง (เช่น C/C++ Source files (*.c;*.cpp) แทน (*.c;*.cpp) ) บนแพลตฟอร์มที่รองรับ
• ผนวกนามสกุลไฟล์โดยอัตโนมัติบนแพลตฟอร์มที่ผู้ใช้คาดหวัง
• รองรับการตั้งค่าเส้นทางโฟลเดอร์เริ่มต้น
• รองรับการตั้งค่าชื่อไฟล์เริ่มต้น (เช่น Untitled.c )
• การสนับสนุน UTF-8 ที่สอดคล้องกันในทุกแพลตฟอร์ม
• ชุดอักขระดั้งเดิม (UTF-16 wchar_t ) รองรับบน Windows
• การเริ่มต้นและการยกเลิกการเริ่มต้นของไลบรารีแพลตฟอร์ม (เช่น com (windows) / gtk (linux gtk) / d-bus (linux portal)) decoupled จากฟังก์ชั่นโต้ตอบดังนั้นแอปพลิเคชันสามารถเลือกเมื่อเริ่มต้น / de-initialize
• การสนับสนุนการเลือกหลายรายการ (สำหรับไฟล์เปิดและโฟลเดอร์เลือกกล่องโต้ตอบ)
• รองรับ IFileDialog ที่ทันสมัยของ Vista บน Windows
• ไม่มีการพึ่งพาของบุคคลที่สาม
• ระบบสร้าง CMAKE ที่ทันสมัย
• ทำงานร่วมกับ SDL2 ในทุกแพลตฟอร์ม
• c ++ wrapper เสริมที่มีความหมาย unique_ptr

เปรียบเทียบกับกล่องโต้ตอบไฟล์ดั้งเดิม:

คุณสมบัติชื่อที่เป็นมิตรเป็นเหตุผลหลักในการทำลายความเข้ากันได้ของ API กับห้องสมุดของ Michael Labbe (และด้วยเหตุนี้ห้องสมุดนี้อาจจะไม่ถูกรวมเข้ากับมัน) นอกจากนี้ยังมีการปรับแต่งจำนวนหนึ่งที่ทำให้เกิดความแตกต่างที่สังเกตได้ในห้องสมุดนี้

เพิ่มคุณสมบัติในกล่องโต้ตอบไฟล์เนทีฟ:

• ชื่อที่เป็นมิตรสำหรับตัวกรอง
• ต่อท้ายการขยายไฟล์โดยอัตโนมัติ
• รองรับการตั้งค่าชื่อไฟล์เริ่มต้น
• ชุดอักขระดั้งเดิม (UTF-16 wchar_t ) รองรับบน Windows
• การสนับสนุน XDG-DESKTOP-Portal บน Linux ที่เปิดตัวเลือกไฟล์ "Native" (ดู "การใช้งาน" ด้านล่าง)
• การสนับสนุนการเลือกโฟลเดอร์หลายรายการ
• การเริ่มต้นและการยกเลิกการเริ่มต้นของไลบรารีแพลตฟอร์มแยกออกจากฟังก์ชั่นกล่องโต้ตอบไฟล์
• ระบบสร้าง CMAKE ที่ทันสมัย
• c ++ wrapper เสริมพร้อมความหมาย unique_ptr ซ้ำกัน

นอกจากนี้ยังมีการหักเหของรหัสที่สำคัญโดยเฉพาะอย่างยิ่งสำหรับการใช้งาน Windows

วิกิติดตามการเชื่อมโยงภาษาที่รู้จักและโครงการยอดนิยมที่รู้จักกันดีซึ่งขึ้นอยู่กับห้องสมุดนี้

การใช้งานขั้นพื้นฐาน

 #include <nfd.h>
#include <stdio.h>
#include <stdlib.h>

int main ( void )
{
    
    NFD_Init ();

    nfdu8char_t * outPath ;
    nfdu8filteritem_t filters [ 2 ] = { { "Source code" , "c,cpp,cc" }, { "Headers" , "h,hpp" } };
    nfdopendialogu8args_t args = { 0 };
    args . filterList = filters ;
    args . filterCount = 2 ;
    nfdresult_t result = NFD_OpenDialogU8_With ( & outPath , & args );
    if ( result == NFD_OKAY )
    {
        puts ( "Success!" );
        puts ( outPath );
        NFD_FreePathU8 ( outPath );
    }
    else if ( result == NFD_CANCEL )
    {
        puts ( "User pressed cancel." );
    }
    else 
    {
        printf ( "Error: %sn" , NFD_GetError ());
    }

    NFD_Quit ();
    return 0 ;
}

U8 / u8 ใน NFDE อ้างถึง API สำหรับอักขระ UTF-8 ( char ) ซึ่งผู้บริโภคส่วนใหญ่อาจต้องการ นอกจากนี้ยังมีเวอร์ชัน N / n ซึ่งใช้ประเภทอักขระดั้งเดิม ( wchar_t บน Windows และ char บนแพลตฟอร์มอื่น ๆ )

สำหรับรายการทั้งหมดของอาร์กิวเมนต์ที่คุณสามารถตั้งค่าบน args struct ดูส่วน "ตัวเลือกทั้งหมด" ด้านล่าง

หากคุณใช้เฟรมเวิร์กที่เป็นนามธรรมของแพลตฟอร์มเช่น SDL หรือ GLFW ให้ดูที่ส่วน "การใช้งานด้วยเฟรมเวิร์กแพลตฟอร์มที่เป็นนามธรรม" ด้านล่าง

ภาพหน้าจอ

อาคาร

โครงการ cmake

หากโครงการของคุณใช้ cmake เพียงเพิ่มบรรทัดต่อไปนี้ใน cmakelists.txt:

 add_subdirectory(path/to/nativefiledialog-extended)
target_link_libraries(MyProgram PRIVATE nfd)

ตรวจสอบให้แน่ใจว่าคุณมีการพึ่งพาที่จำเป็น

เมื่อรวมเป็นโครงการย่อยโปรแกรมตัวอย่างจะไม่ถูกสร้างขึ้นและเป้าหมายการติดตั้งจะถูกปิดใช้งานโดยค่าเริ่มต้น เพิ่ม -DNFD_BUILD_TESTS=ON เพื่อสร้างโปรแกรมตัวอย่างและ -DNFD_INSTALL=ON เพื่อเปิดใช้งานเป้าหมายการติดตั้ง

ห้องสมุดแบบสแตนด์อโลน

หากคุณต้องการสร้างไลบรารีสแตนด์อโลนแบบสแตนด์อโลนให้ดำเนินการคำสั่งต่อไปนี้ (เริ่มต้นจากไดเรกทอรีรากโครงการ):

สำหรับ GCC และ Clang:

 mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build .

สำหรับ MSVC:

 mkdir build
cd build
cmake ..
cmake --build . --config Release

คำสั่งข้างต้นจะ build ไดเรกทอรีบิลด์และสร้างโครงการ (ในโหมดปล่อย) ที่นั่น หากคุณกำลังพัฒนา NFDE คุณอาจต้องการทำ -DCMAKE_BUILD_TYPE=Debug / --config Debug เพื่อสร้างห้องสมุดเวอร์ชันดีบั๊กแทน

เมื่อสร้างเป็นไลบรารีแบบสแตนด์อโลนโปรแกรมตัวอย่างจะถูกสร้างขึ้นและเปิดใช้งานเป้าหมายการติดตั้งโดยค่าเริ่มต้น เพิ่ม -DNFD_BUILD_TESTS=OFF เพื่อปิดการใช้งานโปรแกรมตัวอย่างอาคารและ -DNFD_INSTALL=OFF เพื่อปิดใช้งานการติดตั้งเป้าหมาย

บน Linux หากคุณต้องการใช้พอร์ทัลเดสก์ท็อป Flatpak แทน GTK ให้เพิ่ม -DNFD_PORTAL=ON (มิฉะนั้นจะใช้ GTK) ดูส่วน "การใช้งาน" ด้านล่างสำหรับข้อมูลเพิ่มเติม

ดูไฟล์ CI Build สำหรับคำสั่ง build ตัวอย่าง

Visual Studio บน Windows

Visual Studio เวอร์ชันล่าสุดมีการสนับสนุน CMAKE ที่สร้างขึ้นใน IDE คุณควรจะ "เปิดโฟลเดอร์" ในไดเรกทอรีรูทของโครงการและ Visual Studio จะรับรู้และกำหนดค่าโครงการอย่างเหมาะสม จากตรงนั้นคุณจะสามารถตั้งค่าการกำหนดค่าสำหรับการดีบัก vs release และสำหรับ x86 vs x64 สำหรับข้อมูลเพิ่มเติมดูหน้า Microsoft Docs สิ่งนี้ได้รับการทดสอบเพื่อทำงานกับ Visual Studio 2019 และอาจใช้งานได้กับ Visual Studio 2017 ด้วย

รวบรวมโปรแกรมของคุณ

1. เพิ่ม src/include ไปยังเส้นทางการค้นหาของคุณ
2. เพิ่ม nfd.lib หรือ nfd_d.lib ไปยังรายการของไลบรารีคงที่เพื่อเชื่อมโยงกับ (สำหรับการเปิดตัวหรือการดีบักตามลำดับ)
3. เพิ่ม build/<debug|release>/<arch> ไปยังเส้นทางการค้นหาห้องสมุด

การพึ่งพาอาศัยกัน

ลินเวกซ์

GTK (ค่าเริ่มต้น)

ตรวจสอบให้แน่ใจว่าติดตั้ง libgtk-3-dev ในระบบของคุณ

พอร์ทัล

ตรวจสอบให้แน่ใจว่ามีการติดตั้ง libdbus-1-dev ในระบบของคุณ

แม็กอส

บน MacOS ให้เพิ่ม AppKit และ UniformTypeIdentifiers ลงในรายการเฟรมเวิร์ก

หน้าต่าง

บน Windows (ทั้ง MSVC และ MINGW) ให้แน่ใจว่าคุณกำลังสร้างกับ ole32.lib , uuid.lib และ shell32.lib

การใช้งาน

ตัวเลือกทั้งหมด

ในการเปิดกล่องโต้ตอบคุณตั้งค่าตัวเลือกบน struct แล้วส่งผ่าน struct นั้นไปยังฟังก์ชัน NFDE เช่น:

 nfdopendialogu8args_t args = { 0 };
args . filterList = filters ;
args . filterCount = 2 ;
nfdresult_t result = NFD_OpenDialogU8_With ( & outPath , & args );

ตัวเลือกทั้งหมดเป็นทางเลือกและอาจถูกตั้งค่าเป็นรายบุคคล (ศูนย์เริ่มต้นตั้งค่าตัวเลือกทั้งหมดเป็นค่าเริ่มต้นที่สมเหตุสมผล) ยกเว้น filterList และ filterCount ซึ่งจะต้องเป็นทั้งสองชุดหรือทั้งสองด้านซ้าย UNSET

NFDE เวอร์ชันในอนาคตอาจเพิ่มตัวเลือกเพิ่มเติมในตอนท้ายของโครงสร้างอาร์กิวเมนต์โดยไม่ต้องชนหมายเลขเวอร์ชันหลักดังนั้นเพื่อให้แน่ใจว่าเข้ากันได้กับ API แบบย้อนหลังคุณไม่ควรสันนิษฐานว่าโครงสร้างมีความยาวหรือจำนวนฟิลด์เฉพาะ คุณอาจสันนิษฐานได้ว่า zero-initialization ของ struct จะยังคงตั้งค่าตัวเลือกทั้งหมดเป็นค่าเริ่มต้นที่สมเหตุสมผลดังนั้นการกำหนด {0} ให้กับ struct เป็นที่ยอมรับ สำหรับผู้สร้างห้องสมุดที่ใช้ร่วมกันของ NFDE ความเข้ากันได้ของ ABI ย้อนหลังจะได้รับการรับรองโดยดัชนีเวอร์ชันภายใน ( NFD_INTERFACE_VERSION ) ซึ่งคาดว่าจะโปร่งใสให้กับผู้บริโภค

Opendialog / OpendialogMultiple :

 typedef struct {
    const nfdu8filteritem_t * filterList ;
    nfdfiltersize_t filterCount ;
    const nfdu8char_t * defaultPath ;
    nfdwindowhandle_t parentWindow ;
} nfdopendialogu8args_t ;

บันทึก :

 typedef struct {
    const nfdu8filteritem_t * filterList ;
    nfdfiltersize_t filterCount ;
    const nfdu8char_t * defaultPath ;
    const nfdu8char_t * defaultName ;
    nfdwindowhandle_t parentWindow ;
} nfdsavedialogu8args_t ;

PickFolder / PickFolderMultiple :

 typedef struct {
    const nfdu8char_t * defaultPath ;
    nfdwindowhandle_t parentWindow ;
} nfdpickfolderu8args_t ;

• filterList และ filterCount : ตั้งค่าเหล่านี้เพื่อปรับแต่งตัวกรองไฟล์ (ปรากฏเป็นเมนูแบบเลื่อนลงบน Windows และ Linux แต่เพียงแค่ซ่อนไฟล์บน MACOS) ตั้งค่า filterList เป็นตัวชี้ไปยังจุดเริ่มต้นของอาร์เรย์ของรายการตัวกรองและ filterCount กับจำนวนรายการตัวกรองในอาร์เรย์นั้น ดูส่วน "File Filter Syntax" ด้านล่างสำหรับรายละเอียด
• defaultPath : ตั้งค่านี้เป็นโฟลเดอร์เริ่มต้นที่กล่องโต้ตอบควรเปิดเป็น (บน windows หากมีโฟลเดอร์ที่ใช้เมื่อเร็ว ๆ นี้จะเปิดไปยังโฟลเดอร์นั้นแทนที่จะเป็นโฟลเดอร์ที่คุณผ่านเว้นแต่ว่า NFD_OVERRIDE_RECENT_WITH_DEFAULT Build จะถูกตั้งค่าไว้)
• defaultName : (สำหรับ savedialog เท่านั้น) ตั้งค่าสิ่งนี้เป็นชื่อไฟล์ที่ควรเติมไว้ล่วงหน้าในกล่องโต้ตอบ
• parentWindow : ตั้งค่าสิ่งนี้เป็นที่จับหน้าต่างดั้งเดิมของผู้ปกครองของกล่องโต้ตอบนี้ ดูส่วน "การใช้งานด้วยเฟรมเวิร์กนามธรรมแพลตฟอร์ม" สำหรับรายละเอียด นอกจากนี้ยังเป็นไปได้ที่จะผ่านที่จับแม้ว่าคุณจะไม่ใช้เฟรมเวิร์กที่เป็นนามธรรมของแพลตฟอร์ม

ตัวอย่าง

ดูไดเรกทอรี test ตัวอย่างรหัส (ทั้ง C และ C ++)

หากคุณเปิดตัวเลือกในการสร้างไดเรกทอรี test ( -DNFD_BUILD_TESTS=ON ) build/bin จะมีโปรแกรมทดสอบที่รวบรวมได้

นอกจากนี้ยังมีตัวอย่าง SDL2 ซึ่งจำเป็นต้องเปิดใช้งานแยกต่างหากด้วย -DNFD_BUILD_SDL2_TESTS=ON ต้องติดตั้ง SDL2 บนเครื่องของคุณ

ตัวอย่างที่รวบรวม (รวมถึงตัวอย่าง SDL2) จะถูกอัปโหลดเป็นสิ่งประดิษฐ์ไปยังการกระทำของ GitHub และอาจดาวน์โหลดได้จากที่นั่น

ไวยากรณ์ตัวกรองไฟล์

ไฟล์สามารถกรองโดยกลุ่มนามสกุลไฟล์:

 nfdu8filteritem_t filters [ 2 ] = { { "Source code" , "c,cpp,cc" }, { "Headers" , "h,hpp" } };

ตัวกรองไฟล์เป็นคู่ของสตริงที่ประกอบด้วยชื่อที่เป็นมิตรและข้อมูลจำเพาะ (ส่วนขยายไฟล์หลายรายการถูกแยกออกจากกัน)

รายการตัวกรองไฟล์สามารถส่งผ่านเป็นอาร์กิวเมนต์เมื่อเรียกใช้ไลบรารี

ตัวกรองไวด์การ์ดจะถูกเพิ่มเข้าไปในกล่องโต้ตอบทุกครั้ง

หมายเหตุ: ใน MacOS กล่องโต้ตอบไฟล์ไม่มีชื่อที่เป็นมิตรและไม่มีวิธีสลับระหว่างตัวกรองดังนั้นข้อมูลจำเพาะของตัวกรองจะถูกรวมเข้าด้วยกัน (เช่น "C, CPP, CC, H, HPP") ข้อมูลจำเพาะตัวกรองยังไม่เคยแสดงให้ผู้ใช้อย่างชัดเจน นี่เป็นพฤติกรรม MacOS ปกติและผู้ใช้คาดหวัง

หมายเหตุ 2: คุณต้องตรวจสอบให้แน่ใจว่าสตริงข้อมูลจำเพาะนั้นไม่ว่างเปล่าและทุกส่วนขยายไฟล์มีอักขระอย่างน้อยหนึ่งตัว มิฉะนั้นสิ่งเลวร้ายอาจเกิดขึ้น (เช่นพฤติกรรมที่ไม่ได้กำหนด)

หมายเหตุ 3: บน Linux ส่วนขยายของไฟล์จะถูกผนวกเข้า (ถ้าหายไป) เมื่อผู้ใช้กดปุ่ม "บันทึก" ส่วนขยายไฟล์ที่ต่อท้ายจะยังคงมองเห็นได้สำหรับผู้ใช้แม้ว่าจะมีการแสดงพรอมต์ที่เขียนทับและจากนั้นผู้ใช้ก็กด "ยกเลิก"

หมายเหตุ 4: บน Windows พารามิเตอร์โฟลเดอร์เริ่มต้นจะใช้เฉพาะในกรณีที่ไม่มีโฟลเดอร์ที่ใช้เมื่อเร็ว ๆ นี้เว้นแต่จะมีตัวเลือกการสร้าง NFD_OVERRIDE_RECENT_WITH_DEFAULT Build ถูกตั้งค่าเป็น ON มิฉะนั้นโฟลเดอร์เริ่มต้นจะเป็นโฟลเดอร์ที่ใช้ล่าสุด ภายในการใช้งาน Windows เรียกใช้ iFileDialog :: SetDefaultFolder (IshellItem) นี่เป็นพฤติกรรมของ Windows ปกติและผู้ใช้คาดหวัง

ทำซ้ำผ่านชุดเส้นทาง

กล่องโต้ตอบเปิดไฟล์ที่รองรับการเลือกหลายรายการจะสร้างเส้นทางซึ่งเป็นนามธรรมบาง ๆ เหนือคอลเลกชันเฉพาะแพลตฟอร์ม มีสองวิธีในการทำซ้ำผ่านเส้นทาง:

เข้าถึงโดยดัชนี

วิธีการนี้ไม่เหมือนอาเรย์บนเส้นทางและเป็นวิธีที่ง่ายที่สุดในการใช้งาน อย่างไรก็ตามในบางแพลตฟอร์ม (Linux และ Windows อาจใช้เวลาทั้งหมด (N ² ) ทั้งหมดเพื่อทำซ้ำเส้นทางทั้งหมดเนื่องจากการใช้งานเฉพาะแพลตฟอร์มพื้นฐานใช้รายการที่เชื่อมโยง

ดู test_opendialogmultiple.c

การใช้ enumerator (การทดลอง)

วิธีนี้ใช้วัตถุ enumerator เพื่อทำซ้ำเส้นทางในเส้นทาง รับประกันได้ว่าจะใช้เวลาทั้งหมด (n) ทั้งหมดเพื่อทำซ้ำเส้นทางทั้งหมด

ดู test_opendialogmultiple_enum.c

API นี้เป็นการทดลองและอาจมีการเปลี่ยนแปลง

มาโครการปรับแต่ง

คุณสามารถกำหนดแมโครต่อไปนี้ ก่อน รวม nfd.h / nfd.hpp :

• NFD_NATIVE : กำหนดสิ่งนี้ก่อนรวม nfd.h เพื่อสร้างชื่อฟังก์ชันที่ไม่ได้คัดค้านและ typedefs (เช่น NFD_OpenDialog ) นามแฝงสำหรับฟังก์ชั่นดั้งเดิม (เช่น NFD_OpenDialogN ) แทนนามแฝงสำหรับฟังก์ชัน UTF-8 (เช่น NFD_OpenDialogU8 ) แมโครนี้ไม่ส่งผลกระทบต่อ c ++ wrapper nfd.hpp
• NFD_THROWS_EXCEPTIONS : (c ++ เท่านั้น) กำหนดสิ่งนี้ก่อนรวมถึง nfd.hpp เพื่อสร้าง NFD::Guard construction โยน std::runtime_error ถ้า NFD_Init ล้มเหลว มิฉะนั้นจะไม่มีวิธีตรวจสอบความล้มเหลวใน NFD::Guard Construction

มาโครที่อาจกำหนดโดย nfd.h :

• NFD_DIFFERENT_NATIVE_FUNCTIONS : กำหนดถ้าฟังก์ชันดั้งเดิมและ UTF-8 นั้นแตกต่างกัน (เช่นการรวบรวมสำหรับ Windows); ไม่ได้กำหนดไว้เป็นอย่างอื่น หากไม่ได้กำหนด NFD_DIFFERENT_NATIVE_FUNCTIONS แล้วฟังก์ชั่นเวอร์ชัน UTF-8 จะเป็นนามแฝงสำหรับเวอร์ชันดั้งเดิม สิ่งนี้อาจมีประโยชน์หากคุณกำลังเขียนฟังก์ชั่นที่ต้องการให้โอเวอร์โหลดขึ้นอยู่กับว่าฟังก์ชั่นดั้งเดิมและฟังก์ชั่น UTF-8 นั้นเหมือนกันหรือไม่ (ดั้งเดิมคือ UTF-16 ( wchar_t ) สำหรับ Windows และ UTF-8 ( char ) สำหรับ Mac/Linux)

การใช้งานด้วยกรอบนามธรรมของแพลตฟอร์ม

NFDE เป็นที่รู้จักกันในการทำงานกับ SDL2 และ GLFW และควรทำงานร่วมกับเฟรมที่เป็นนามธรรมแพลตฟอร์มอื่น ๆ ส่วนนี้อธิบายวิธีการใช้ NFDE อย่างถูกต้องกับเฟรมเวิร์กดังกล่าว

ที่จับหน้าต่างแม่

อาร์กิวเมนต์ parentWindow อนุญาตให้ผู้ใช้ให้คำโต้ตอบกับพาเรนต์

หากใช้ SDL2 ให้รวม <nfd_sdl2.h> และเรียกใช้ฟังก์ชันต่อไปนี้เพื่อตั้งค่าที่จับหน้าต่างพาเรนต์:

 NFD_GetNativeWindowFromSDLWindow ( sdlWindow /* SDL_Window* */ , & args . parentWindow );

หากใช้ glfw3 ให้กำหนด GLFW_EXPOSE_NATIVE_* ที่เหมาะสมที่อธิบายไว้ในหน้า GLFW Native Access จากนั้นรวม <nfd_glfw3.h> และเรียกใช้ฟังก์ชั่นต่อไปนี้เพื่อตั้งค่าที่จับหน้าต่างหลัก:

 NFD_GetNativeWindowFromGLFWWindow ( glfwWindow /* GLFWwindow* */ , & args . parentWindow );

หากคุณใช้เฟรมเวิร์กที่เป็นนามธรรมแพลตฟอร์มอื่นหรือไม่ใช้เฟรมเวิร์กดังกล่าวคุณสามารถตั้งค่า args.parentWindow ด้วยตนเอง

รองรับ Win32 (Windows), Cocoa (MacOS) และ X11 (Linux) Windows ขณะนี้ผ่านหน้าต่าง Wayland (Linux) ไม่ได้ทำอะไรเลย

ทำไมต้องผ่านที่จับหน้าต่างแม่?

ในการสร้างหน้าต่าง (ในกรณีนี้กล่องโต้ตอบไฟล์) อยู่เหนือหน้าต่างอื่นเราจำเป็นต้องประกาศหน้าต่างด้านล่างเป็นพาเรนต์ของหน้าต่างด้านบน สิ่งนี้จะช่วยให้หน้าต่างโต้ตอบหายไปด้านหลังหน้าต่างพาเรนต์หากผู้ใช้คลิกที่หน้าต่างพาเรนต์ในขณะที่กล่องโต้ตอบเปิดอยู่ การรักษากล่องโต้ตอบเหนือหน้าต่างที่เรียกใช้เป็นพฤติกรรมที่คาดหวังในระบบปฏิบัติการที่รองรับทั้งหมดและแนะนำให้ส่งผ่านหน้าต่างหลักที่จับได้หากเป็นไปได้

ลำดับการเริ่มต้น

คุณควรเริ่มต้น NFDE หลังจาก เริ่มต้นเฟรมเวิร์กและอาจจะ deinitialize NFDE ก่อนที่ จะ deinitializing เฟรมเวิร์ก นี่เป็นเพราะเฟรมเวิร์กบางอย่างคาดว่าจะเริ่มต้นใน "กระดานชนวนสะอาด" และพวกเขาอาจกำหนดค่าระบบในวิธีที่แตกต่างจาก NFDE โดยทั่วไปแล้ว NFD_Init จะระมัดระวังอย่างยิ่งที่จะไม่ขัดขวางการกำหนดค่าที่มีอยู่เว้นแต่จำเป็นและ NFD_Quit จะคืนค่าการกำหนดค่ากลับคืนสู่สิ่งที่เป็นก่อนการเริ่มต้น

ตัวอย่างด้วย SDL2:

 // Initialize SDL2 first
if (SDL_Init(SDL_INIT_VIDEO|SDL_INIT_AUDIO) != 0) {
    // display some error here
}

// Then initialize NFDe
if (NFD_Init() != NFD_OKAY) {
    // display some error here
}

/*
Your main program goes here
*/

NFD_Quit(); // deinitialize NFDe first

SDL_Quit(); // Then deinitialize SDL2

การใช้ XDG-Desktop-Portal บน Linux

บน Linux คุณสามารถใช้การใช้งานพอร์ทัลแทน GTK ซึ่งจะเปิดตัวเลือกไฟล์ "เนทีฟ" ที่เลือกโดยระบบปฏิบัติการหรือปรับแต่งโดยผู้ใช้ ผู้ใช้จะต้องมี xdg-desktop-portal และแบ็กเอนด์ที่เหมาะสมที่ติดตั้ง (ซึ่งติดตั้งไว้ล่วงหน้าด้วยเดสก์ท็อปที่พบบ่อยที่สุด) มิฉะนั้นจะส่งคืน NFD_ERROR

หากต้องการใช้การใช้งานพอร์ทัลให้เพิ่ม -DNFD_PORTAL=ON คำสั่ง build

*หมายเหตุ: ตัวเลือกโฟลเดอร์ได้รับการสนับสนุนเฉพาะใน org.freedesktop.portal.filechooser อินเตอร์เฟสเวอร์ชัน> = 3 ซึ่งสอดคล้องกับ XDG-Desktop-Portal เวอร์ชัน> = 1.7.1 NFD_PickFolder() จะสอบถามเวอร์ชันอินเตอร์เฟสที่รันไทม์และส่งคืน NFD_ERROR หากเวอร์ชันต่ำเกินไป

พอร์ทัลคืออะไร?

Linux ไม่ได้มีตัวเลือกไฟล์ที่อบเข้ากับระบบปฏิบัติการ แอปพลิเคชัน Linux ที่ต้องการตัวเลือกไฟล์มักจะเชื่อมโยงกับไลบรารีที่ให้บริการหนึ่งรายการ (เช่น GTK เช่นเดียวกับในภาพหน้าจอ Linux ด้านบน) นี่เป็นโซลูชันที่ยอมรับได้ส่วนใหญ่ที่แอปพลิเคชันจำนวนมากใช้ แต่อาจทำให้ตัวเลือกไฟล์ดูต่างประเทศใน distros ที่ไม่ใช่ GTK

Flatpak เปิดตัวในปี 2558 และด้วยอินเทอร์เฟซที่ได้มาตรฐานเพื่อเปิดตัวเลือกไฟล์ แอปพลิเคชันที่ใช้อินเทอร์เฟซนี้ไม่จำเป็นต้องมาพร้อมกับตัวเลือกไฟล์และสามารถใช้แอปพลิเคชันที่ Flatpak ให้ไว้ อินเทอร์เฟซนี้กลายเป็นที่รู้จักกันในชื่อพอร์ทัลเดสก์ท็อปและการใช้งานขยายไปยังแอปพลิเคชันที่ไม่ใช่ Flatpak ตอนนี้เดสก์ท็อป Linux distros ที่สำคัญที่สุดมาพร้อมกับพอร์ทัลเดสก์ท็อปที่ติดตั้งพร้อมตัวเลือกไฟล์ที่เหมาะสมกับธีมของ distro ผู้ใช้ยังสามารถติดตั้งแบ็กเอนด์พอร์ทัลอื่นได้หากต้องการ ขณะนี้มีแบ็กเอนด์ที่รู้จักกันสามประการพร้อมการสนับสนุนตัวเลือกไฟล์: GTK, KDE และ LXQT; แบ็กเอนด์ Gnome และ Xapp ขึ้นอยู่กับ GTK One สำหรับฟังก์ชั่นนี้ แบ็กเอนด์ XAPP ได้รับการออกแบบมาสำหรับอบเชยคู่และ XFCE สภาพแวดล้อมเดสก์ท็อปอื่น ๆ ดูเหมือนจะไม่มีแบ็กเอนด์พอร์ทัล

นิสัยใจคอเฉพาะของแพลตฟอร์ม

แม็กอส

• หากเป้าหมายการปรับใช้ MACOS คือ≥ 11.0 คุณสมบัติที่อนุญาตให้ใช้งานของ NSSavePanel จะถูกใช้แทนคุณสมบัติที่ได้รับอนุญาต FileTypes สำหรับตัวกรองไฟล์ ดังนั้นหากคุณกำลังกรองโดยนามสกุลไฟล์ที่กำหนดเองเฉพาะกับแอปพลิเคชันของคุณคุณจะต้องกำหนดชนิดข้อมูลในไฟล์ Info.plist ของคุณตามเอกสารของ Apple (เป็นไปได้ที่จะบังคับให้ NFDE ใช้ FileTypes ที่ได้รับอนุญาตโดยการเพิ่ม -DNFD_USE_ALLOWEDCONTENTTYPES_IF_AVAILABLE=OFF คำสั่ง cmake build ของคุณ แต่ไม่แนะนำให้ใช้หากคุณต้องการสนับสนุนรุ่น MACOS รุ่นเก่าคุณควรตั้งเป้าหมายการปรับใช้ที่ถูกต้องแทน)

ข้อ จำกัด ที่รู้จัก

• ไม่มีการรองรับกล่องโต้ตอบมรดกของ Windows XP เช่น GetOpenFileName (ไม่มีแผนที่จะสนับสนุนสิ่งนี้คุณไม่ควรใช้ Windows XP อยู่ดี)
• ไม่มีการผูก eMscripten (webAssembly) (สิ่งนี้อาจถูกนำไปใช้ถ้าฉันตัดสินใจที่จะพอร์ตวงจร Sandbox สำหรับเว็บ แต่ฉันไม่คิดว่าจะมีวิธีใดในการใช้ตัวเลือกโฟลเดอร์บนเว็บ)
• กล่องโต้ตอบ GTK ไม่ได้ตั้งค่าหน้าต่างที่มีอยู่เป็นพาเรนต์ดังนั้นหากผู้ใช้คลิกหน้าต่างที่มีอยู่ในขณะที่กล่องโต้ตอบเปิดออกแล้วกล่องโต้ตอบจะไปด้านหลัง GTK เขียนคำเตือนถึง stdout หรือ stderr เกี่ยวกับเรื่องนี้
• ไลบรารีนี้เข้ากันไม่ได้กับไลบรารีไดอะล็อกไฟล์ดั้งเดิม สิ่งต่าง ๆ อาจแตกหักถ้าคุณใช้ทั้งสองในโครงการเดียวกัน (ไม่มีแผนที่จะสนับสนุนสิ่งนี้คุณต้องใช้อย่างใดอย่างหนึ่ง)
• ไลบรารีนี้ไม่ได้ส่งการโทรไปยังเธรด UI อย่างชัดเจน สิ่งนี้อาจนำไปสู่การขัดข้องหากคุณเรียกฟังก์ชั่นจากเธรดอื่นเมื่อแพลตฟอร์มไม่รองรับ (เช่น MacOS) โดยทั่วไปผู้ใช้คาดว่าจะโทรหา NFDE จากเธรด UI ที่เหมาะสม (เช่นเธรดที่ทำลูปเหตุการณ์ UI)

การรายงานข้อบกพร่อง

โปรดใช้ตัวติดตามปัญหา GitHub เพื่อรายงานข้อบกพร่องหรือเพื่อสนับสนุนที่เก็บนี้ อย่าลังเลที่จะส่งรายงานข้อผิดพลาดทุกชนิด

เครดิต

Bernard Teo (Me) และผู้มีส่วนร่วมอื่น ๆ สำหรับทุกสิ่งที่ไม่ได้มาจากกล่องโต้ตอบไฟล์ดั้งเดิมของ Michael Labbe

Michael Labbe สำหรับห้องสมุดกล่องโต้ตอบไฟล์พื้นเมืองที่ยอดเยี่ยมของเขาและผู้มีส่วนร่วมอื่น ๆ ในห้องสมุดนั้น

ส่วนใหญ่ของ readme นี้ได้รับการคัดลอกจาก readme ของที่เก็บโต้ตอบไฟล์ดั้งเดิม

ใบอนุญาต

ทุกอย่างในที่เก็บนี้มีการแจกจ่ายภายใต้ใบอนุญาต ZLIB เช่นเดียวกับไลบรารีกล่องโต้ตอบไฟล์ดั้งเดิม

สนับสนุน

ฉันไม่ได้ให้การสนับสนุนใด ๆ Michael Labbe ดูเหมือนจะให้การสนับสนุนที่ได้รับค่าตอบแทนสำหรับห้องสมุดของเขาในเวลาที่เขียน