| 1 |
# (C) Copyright 2004-2023 Enthought, Inc., Austin, TX |
| 2 |
# All rights reserved. |
| 3 |
# |
| 4 |
# This software is provided without warranty under the terms of the BSD |
| 5 |
# license included in LICENSE.txt and may be redistributed only under |
| 6 |
# the conditions described in the aforementioned license. The license |
| 7 |
# is also available online at http://www.enthought.com/licenses/BSD.txt |
| 8 |
# |
| 9 |
# Thanks for using Enthought open source! |
| 10 |
|
| 11 |
""" |
| 12 |
**WARNING** |
| 13 |
|
| 14 |
This demo might not work as expected and some documented features might be |
| 15 |
missing. |
| 16 |
|
| 17 |
------------------------------------------------------------------------------- |
| 18 |
|
| 19 |
This demonstrates one of the simplest cases of using the TraitsUI file dialog |
| 20 |
to select a file for opening (i.e. reading or editing). |
| 21 |
|
| 22 |
The first question of course is why use the TraitsUI file dialog at all, when |
| 23 |
the standard OS file dialog is also available? |
| 24 |
|
| 25 |
And the answer is that you can use either, but the advantages of using the |
| 26 |
TraitsUI file dialog are: |
| 27 |
|
| 28 |
- It supports history. That is, each time the user selects a file for opening, |
| 29 |
the file is added to a persistent history list, similar to many applications |
| 30 |
*Open recent...* function, but built directly into the file dialog. |
| 31 |
The amount of history remembered can be specified by the developer, with the |
| 32 |
default being the last 10 files opened. |
| 33 |
|
| 34 |
- It is resizable. Some standard OS file dialogs are not resizable, which can |
| 35 |
be very annoying to the user trying to select a file through a tiny |
| 36 |
peephole view of the file system. In addition, if the user resizes the |
| 37 |
dialog, the new size and position will be persisted, so that the file dialog |
| 38 |
will appear in the same location the next time the user wants to open a |
| 39 |
file. |
| 40 |
|
| 41 |
- There is a very nice synergy between the file system view and the history |
| 42 |
list. Quite often users shuttle between several *favorite* locations in |
| 43 |
the file system when opening files. The TraitsUI file dialog automatically |
| 44 |
discovers these favorite locations just by the user opening files. When a |
| 45 |
user opens the file dialog, they can select a previously opened file from |
| 46 |
the history list, which then automatically causes the file system view to |
| 47 |
expand the selected file's containing folder, thus allowing them to select a |
| 48 |
different file in the same location. Since the history list is updated each |
| 49 |
time a user selects a file, It tends to automatically discover a *working |
| 50 |
set* of favorite directories just through simple use, without the user |
| 51 |
having to explicitly designate them as such. |
| 52 |
|
| 53 |
- It's customizable. The TraitsUI file dialog accepts extension objects which |
| 54 |
can be used to display additional file information or even modify the |
| 55 |
selection behavior of the dialog. Several extensions are provided with |
| 56 |
TraitsUI (and are demonstrated in some of the other examples), and you are |
| 57 |
free to write your own by implementing a very simple interface. |
| 58 |
|
| 59 |
- The history and user settings are customizable per application. Just by |
| 60 |
setting a unique id in the file dialog request, you can specify that the |
| 61 |
history and window size and position information are specific to your |
| 62 |
application. If you have file dialog extensions added, the user can |
| 63 |
reorder, resize and reconfigure the overall file dialog layout, including |
| 64 |
your extensions, and have their custom settings restored each time they use |
| 65 |
the file dialog. If you do not specify a unique id, then the history and |
| 66 |
user settings default to the system-wide settings for the file dialog. It's |
| 67 |
your choice. |
| 68 |
|
| 69 |
- It's easy to use. That's what this particular example is all about. So take |
| 70 |
a look at the source code for this example to see how easy it is... |
| 71 |
""" |
| 72 |
# Issue related to the demo warning: enthought/traitsui#953 |
| 73 |
|
| 74 |
from traits.api import HasTraits, File, Button |
| 75 |
|
| 76 |
from traitsui.api import View, HGroup, Item |
| 77 |
|
| 78 |
from traitsui.file_dialog import open_file |
| 79 |
|
| 80 |
|
| 81 |
# -- FileDialogDemo Class ------------------------------------------------- |
| 82 |
class FileDialogDemo(HasTraits): |
| 83 |
|
| 84 |
# The name of the selected file: |
| 85 |
file_name = File() |
| 86 |
|
| 87 |
# The button used to display the file dialog: |
| 88 |
open = Button('Open...') |
| 89 |
|
| 90 |
# -- Traits View Definitions ---------------------------------------------- |
| 91 |
|
| 92 |
traits_view = View( |
| 93 |
HGroup( |
| 94 |
Item('open', show_label=False), |
| 95 |
'_', |
| 96 |
Item('file_name', style='readonly', springy=True), |
| 97 |
), |
| 98 |
width=0.5, |
| 99 |
) |
| 100 |
|
| 101 |
# -- Traits Event Handlers ------------------------------------------------ |
| 102 |
|
| 103 |
def _open_changed(self): |
| 104 |
"""Handles the user clicking the 'Open...' button.""" |
| 105 |
file_name = open_file() |
| 106 |
if file_name != '': |
| 107 |
self.file_name = file_name |
| 108 |
|
| 109 |
|
| 110 |
# Create the demo: |
| 111 |
demo = FileDialogDemo() |
| 112 |
|
| 113 |
# Run the demo (if invoked from the command line): |
| 114 |
if __name__ == '__main__': |
| 115 |
demo.configure_traits() |