Smalltalk/X Webserver

Documentation of class 'FileSelectionBox':

Class: FileSelectionBox

Inheritance
Description
Class protocol
Instance protocol
Examples

Inheritance:

   Object
   |
   +--GraphicsMedium
      |
      +--DisplaySurface
         |
         +--SimpleView
            |
            +--View
               |
               +--TopView
                  |
                  +--StandardSystemView
                     |
                     +--ModalBox
                        |
                        +--DialogBox
                           |
                           +--EnterBox
                              |
                              +--ListSelectionBox
                                 |
                                 +--FileSelectionBox
                                    |
                                    +--FileSaveBox

Package:: stx:libwidg

Category:: Views-DialogBoxes

Version:: rev: 1.82 date: 2023/10/05 08:15:59; user: stefan; file: FileSelectionBox.st directory: libwidg; module: stx stc-classLibrary: libwidg

Description:

this class implements file selection boxes. Instances show a list of
files, and perform an action block with the selected pathname as
argument when ok is clicked. It is also possible, to open the box
without action and ask it afterward if it has been left with ok
(i.e. the ST-80 way, asking 'aBox accepted ifTrue:[...]')

There is an optional PatternField, which shows itself when a pattern
is defined (i.e. if there is no pattern, it is hidden). 
If there is a pattern, only files matching the pattern are shown in 
the list. Directories are not affected by the patternField.

In addition, there is an optional matchBlock (actually this is defined 
in the FileSelectionList). Only names for which this matchblock
returns true will be presented. The matchBlock affects both regular files
and names of directories. The argument passed to the matchBlock is the full
pathname.

All of the actual work is done in the fileList; see the documentation
of FileSelectionList for more options 
(you can access a boxes fileList via 'aBox>>listView' and get access to all
 of those fancy settings)
For example, by accessing the list, it is possible to hide all directories 
('aBox listView ignoreDirectories:true'), to hide the parentDirectory alone 
('aBox listView ignoreParentDirectory') and to turn off the marking 
of subdirectories ('aBox listView markSubdirectories:false').

copyrightCOPYRIGHT (c) 1990 by Claus Gittinger
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

Class protocol:

accessing

lastFileSelectionDirectory: return the name of the directory used in the previous
fileSelection dialog. This will be used as default for the next dialog,
if no explicit path is specified (see requestFileName:* methods)
lastFileSelectionDirectory: aDirectoryString: set the name of the directory used in the previous
fileSelection dialog. This will be used as default for the next dialog,
if no explicit path is specified (see requestFileName:* methods)
lastSuffixPatternUsedForDefault: default: return the suffix pattern used in the previous fileSelection dialog,
IFF it was changed from default by the user.
This will be used as default for the next dialog, if the same default is coming
lastSuffixPatternUsedForDefault: default is: newPattern: return the suffix pattern used in the previous fileSelection dialog,
IFF it was changed from default by the user.
This will be used as default for the next dialog, if the same default is coming

defaults

listViewType: return the type of listView - using a FileSelectionList here

menu specs

fileListMenu

This resource specification was automatically generated
by the MenuEditor of ST/X.

Usage example(s):

     MenuEditor new openOnClass:FileSelectionBox andSelector:#fileListMenu
     (Menu new fromLiteralArrayEncoding:(FileSelectionBox fileListMenu)) startUp

Instance protocol:

accessing

allowMakeDirectory: aBoolean: allow or deny creation of new directories;
The default is to allow it.
contents: return the current entered value (i.e. the enterFields string).
redefined to return the full pathname.
directory: return the directory which is currently shown
directory: directoryName: change the directory shown in the list.
fileName: if some filename has been entered, return it (without the directory path)
otherwise, return nil
matchBlock: aBlock: set the matchBlock (in the selectionList). Only files
for which the block returns true are shown.
The matching is actually done in the fileSelectionList.
openOn: aPath: open the box showing files in aPath.
This is only a shortcut message - no new functionality.
pathName: same as contents - return the full pathname of the selected file,
or the pathname of the directory if nothing has been entered
pattern: aPattern: set the pattern - this also enables the PatternField
(if the pattern is non-nil) or hides it (if nil).
selectingDirectory: aBoolean: setup the box for directory selection (hides regular files).
Use this, to ask the user for a directories name

change & update

update: something with: argument from: changedObject: sent by fileNameEnterField, if a filename
completion was not possible due to multiple
matches.

initialization

createEnterField: if the (optional) class FilenameEditField is present, use
it, since it provides filename completion. Otherwise, we have
to live with the dumb (default) field ...
initialize: IncludingBorder
postRealize: if some default is present in the enterField,
scroll to make this one visible

menu

fileListMenu
fileListMenuNewFolder: self open
fileListMenuRemove

private

updateList: (comment from inherited method)
setup contents of list;
nothing done here but typically redefined in subclasses.
updateListWithoutScrolling

queries

computePreferredExtent: return my preferred extent
- that's the minimum size to make everything visible

user actions

directoryChanged
directorySelected: a directory was selected - show the new path in the inputField,
if we are in directory mode
doubleClick: (comment from inherited method)
doubleClick on an entry is select & ok
enterFieldChanged
okPressed: called for both on ok-press and on return-key
patternChanged
selectionChanged: (comment from inherited method)
selections in list get forwarded to enterfield

Examples:

simple standard queries (notice, that the receiver of those messages is Dialog - this should always be done for compatibility - although the real fileBox implementation is here). very simple:

      |name|

      name := Dialog requestFileName.
      Transcript showCR:name

simple:

      |name|

      name := FileSelectionBox requestFileName:'which file ?'.
      Transcript showCR:name

with initial selection:

      |name|

      name := FileSelectionBox requestFileName:'which file ?' default:'Make.proto'.
      Transcript showCR:name

more detailed setup setting title:

      |box|
      box := FileSelectionBox new.
      box title:'Which file ?'.
      box open.
      box accepted ifTrue:[
          Transcript showCR:'you selected: ' , box pathName
      ]

setting a matchpattern:

      |box|
      box := FileSelectionBox new.
      box title:'Which file ?'.
      box pattern:'*.rc'.
      box open

setting multiple patterns:

      |box|
      box := FileSelectionBox new.
      box title:'Which file ?'.
      box pattern:'*.rc;*.st'.
      box open

setting a matchblock:

      |box|
      box := FileSelectionBox new.
      box title:'Which file ?'.
      box directory:'/etc'.
      box pattern:'*'.
      box matchBlock:[:name | name asFilename baseName first between:$a and:$z].
      box open

both pattern and matchBlock:

      |box|
      box := FileSelectionBox new.
      box title:'Which directory ?'.
      box selectingDirectory:true.
      box pattern:'l*'.
      box matchBlock:[:name | OperatingSystem isDirectory:name].
      box action:[:fn | Transcript showCR:fn].
      box open

don't show the parent directory:

      |box|
      box := FileSelectionBox new.
      box title:'Which directory ?'.
      box listView ignoreParentDirectory:true.
      box open

don't show any directory:

      |box|
      box := FileSelectionBox new.
      box title:'Which file ?'.
      box listView ignoreDirectories:true.
      box open

don't show any directory or hidden file: (notice the basename extraction - we are not interested in the full pathName)

      |box|
      box := FileSelectionBox new.
      box title:'Which file ?'.
      box listView ignoreDirectories:true.
      box matchBlock:[:name | (name asFilename baseName startsWith:'.') not].
      box open

don't allow direct filename entry: (i.e. avoid the user choosing files from other directories)

      |box|
      box := FileSelectionBox new.
      box title:'Which one ?'.
      box enterField beInvisible.
      box open.
      box accepted ifTrue:[
          Transcript showCR:'path is ' , box pathName
      ].

combined with above directory ignoring, this limits selection of files from a single directory:

      |box|
      box := FileSelectionBox new.
      box title:'Which file ?'.
      box enterField beInvisible.
      box listView ignoreDirectories:true.
      box open.
      box accepted ifTrue:[
          Transcript showCR:'path is ' , box pathName
      ].

finally, an action:

      |box|
      box := FileSelectionBox new.
      box title:'Which directory ?'.
      box pattern:'l*'.
      box matchBlock:[:name | OperatingSystem isDirectory:name].
      box action:[:name | Transcript showCR:name].
      box open

concrete examples: only show files beginning with lowercase characters and ending in '.c':

      |box|
      box := FileSelectionBox new.
      box title:'Which directory ?'.
      box matchBlock:[:name |
                          box pathName asFilename isDirectory
                          or:[name first isLowercase
                              and:[name endsWith:'.c']]
                     ].
      box open.
      box accepted ifTrue:[
          Transcript showCR:'full path:  ' , box pathName.
          Transcript showCR:'files name: ' , box fileName.
          Transcript showCR:'directory : ' , box directory pathName.
      ]

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Sun, 22 Dec 2024 02:23:46 GMT