Merge pull request #156 from kujirahand/samples_for_148

Samples for #148
This pull request improves the documentation and usability of the popup_get_file dialog in the TkEasyGUI library, and enhances the overall clarity of the README and API documentation. The main changes include expanded usage examples and parameter explanations for file dialogs, updates to installation instructions, and alignment of documentation with recent code changes.

Author: kujirahand

README.md

@@ -6,6 +6,8 @@
 
 `TkEasyGUI` is the easiest library for creating GUIs in Python.
 
+<img src="https://github.com/kujirahand/tkeasygui-python/raw/main/docs/image/icon256.png" width="256" alt="TkEasyGUI is the easiest library for creating GUIs in Python.">
+
 This library allows you to easily create GUI applications with Python.
 Since it is based on Tkinter, it runs consistently on Windows, macOS, and Linux.
 With a variety of built-in dialogs and customizable forms, you can develop applications effortlessly.
@@ -23,6 +25,7 @@ With a variety of built-in dialogs and customizable forms, you can develop appli
 Install package from [PyPI](https://pypi.org/project/TkEasyGUI/).
 
 ```sh
+# Install package from PyPI
 pip install TkEasyGUI
 # or
 python -m pip install TkEasyGUI
@@ -31,7 +34,13 @@ python -m pip install TkEasyGUI
 Install package from [GitHub Repository](https://github.com/kujirahand/tkeasygui-python).
 
 ```sh
+# Install package from GitHub Repository
 python -m pip install git+https://github.com/kujirahand/tkeasygui-python
+# or
+# Clone the repository and install
+git clone https://github.com/kujirahand/tkeasygui-python
+cd tkeasygui-python
+python -m pip install .
 ```
 
 ## Features of This Library
@@ -79,6 +88,17 @@ if form:
 
 <img src="https://github.com/kujirahand/tkeasygui-python/raw/main/docs/image/sample3.png" width="300" alt="TkEasyGUI">
 
+A file selection dialog is also available.
+
+```py
+import TkEasyGUI as eg
+# Show File dialog
+file_path = eg.popup_get_file("Select a file")
+eg.print(f"You selected: {file_path}")
+```
+
+<img src="https://github.com/kujirahand/tkeasygui-python/raw/main/docs/image/sample-popup_get_file.png" width="300" alt="TkEasyGUI">
+
 ### More Dialogs
 
 `TkEasyGUI` provides a variety of dialogs. For example, a color selection dialog, a file selection dialog, and a calendar dialog.
@@ -176,8 +196,6 @@ There are other helpful articles as well.
 - Methods such as Copy, Paste, and Cut are added to text boxes (Multiline/Input).
 - The system's default color scheme is utilized.
 
-<img src="https://github.com/kujirahand/tkeasygui-python/raw/main/docs/image/icon256.png" width="256" alt="TkEasyGUI Logo">
-
 ## Additional Information
 
 ### How to run on Raspberry Pi?

TkEasyGUI/dialogs.py

@@ -718,7 +718,32 @@ def popup_get_file(
     no_window: Optional[bool] = None,  # for compatibility
     **kw,
 ) -> Optional[str]:
-    """Popup a file selection dialog. Return the file selected."""
+    """
+    Popup a file selection dialog. Return the file selected.
+
+    - if `save_as` is False, show open file dialog.
+    - if `save_as` is True, show save as dialog.
+    - if `multiple_files` is True, can select multiple files and return a string joined by `files_delimiter`(default is FILES_DELIMITER).
+    - `file_types` is a list of tuples (description, file extension) or a list of file extensions. For example: [("Text Files", "*.txt"), ("All Files", "*.*")] or ["*.txt", "*.py"].
+
+    ```py
+    import TkEasyGUI as eg
+
+    # select a file to open
+    file_path = eg.popup_get_file("Select a file to open:", "Open File")
+    print(file_path)
+    # select a file to save
+    save_path = eg.popup_get_file("Select a file to save:", "Save File", save_as=True)
+    print(save_path)
+    # select multiple files
+    files = eg.popup_get_file("Select files:", "Open Files", multiple_files=True)
+    files_list = files.split(eg.FILES_DELIMITER) if files else []
+    eg.popup_listbox(files_list, "Selected Files")
+    # select only text files
+    text_file = eg.popup_get_file("Select a text file:", "Open Text File", file_types=[("Text Files", "*.txt")])
+    print(text_file)
+    ```
+    """
     from . import widgets as eg
 
     if title is None: