Debian Codegraph @

traitsui/examples/demo/Standard_Editors/File_Dialog/File_Open.py

raw
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()