Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
MIDP3.0
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.microedition.lcdui
Class FileSelector

java.lang.Object
  extended by javax.microedition.lcdui.Displayable
      extended by javax.microedition.lcdui.Screen
          extended by javax.microedition.lcdui.FileSelector

public class FileSelector
extends Screen

The FileSelector class allows the user to select a file from file system to be loaded, saved, or to select a directory. The FileSelector maintains the confidentiality of the filesystem by revealing only the URL of the file or directory explicitly selected by the user. The application only receives information and access to the file permitted by the user. The directory and file names passed to and returned by the FileSelector are formatted as fully qualified absolute file URLs [RFC3986].

FileSelector has two fixed, built-in Commands: OK_COMMAND and CANCEL_COMMAND. It is not possible to add any other commands or menus to or remove commands or menus from FileSelector.

When the user selects a file or directory with a FileSelector and pressed OK, the CommandListener is called with an OK_COMMAND event. Similarly, if the user dismisses the FileSelector by selecting Cancel, the command listener is called with a CANCEL_COMMAND event. These two operations, OK and Cancel, MUST be accessible to the user in any FileSelector. If the screen is dismissed without any user action, the listener MUST NOT be called.

When the user selects OK, the getURL method MUST return the URL of the user selected file or directory depending on the mode. The application can call Connector.open with this URL and access will be subject to the security model and policy. The application can also call the FileSelector.open method and access the content via the Connection it returns. Since the user has explicitly given the MIDlet access to the file, no additional security prompts are required. Implementations MAY combine security prompts for access to the file with the FileSelector. In LOAD and SAVE mode, the getURL method MUST return null unless the user has selected the file and pressed OK; whereas in DIRECTORY_SELECT and DIRECTORY_CREATE mode, the getURL method MUST return null unless the user has selected any directory and pressed OK. After selecting Cancel the getURL method must return null. It is up to the application to change the current displayable in response to the OK or Cancel command.

FileSelector has four modes, LOAD, SAVE, DIRECTORY_SELECT, and DIRECTORY_CREATE. The mode affects the behavior of the dialog:

If the implementation allows the user to type a file name or directory name and the requested action is not successful, then the implementation MUST show an implementation specific warning with the appropriate reason. Reasons may include, but are not limited, to the following:

The FileSelector's CommandListener MUST not be called if the requested action is not completed successfully.

Example Using FileSelector

This example shows the use of the FileSelector to select an image based on the file suffix. The open method is used to get a StreamConnection to the contents and then to create an Image from the stream. The Image is added to an Alert asking the user to confirm the image. This part of the example can be used on any implementation of this specification that has a file system.

The second part of the example, to delete the image, requires the JSR-75 FileConnection API to be implemented by the device. When the delete command is selected then the FileConnection.delete method is called. 

 public class FileSelectDelete implements CommandListener {

      Display display;
      String title;
      FileSelector fs;
      Displayable oldCurrent;
      String[] filterStrings = {"png", "gif", "jpeg"};

      Command DELETE_COMMAND = new Command("Delete", Command.SCREEN, 2);
      Command CANCEL_COMMAND = new Command("Cancel", Command.SCREEN, 1);


      /**
       * Delete a user selected file; with a confirmation.
       * /
      void deleteImage(Display display, String title) {
          this.display = display;
          this.title = title;
          oldCurrent = display.getCurrent();
          fs = new FileSelector(title, FileSelector.SAVE);
          fs.setFilterExtensions(filterStrings);
          fs.setCommandListener(this);
          display.setCurrent(fs);
      }

      /**
       * Handle the OK or Cancel command from the user.
       * In all cases, an Alert is displayed and when dismissed,
       * the previous displayable is restored.
       * The errors for incorrect file path or type put up alerts.
       * If it was ok, then try to display the selected file as an image
       * and provide commands to Delete and cancel the delete.
       * Use the FileConnection to delete the file.
       *
       * @param c The command selected by the user
       * @param d the Displayable containing the command (FileSelector)
       * /
      public void commandAction(Command c, Displayable d) {
          Alert alert = null;
          if (c == FileSelector.OK_COMMAND) {
              // Invoked when user selects OK from FileSelector
              StreamConnection conn = null;
             try {
                  conn = (StreamConnection) fs.open(Connector.READ, false);
                  Image image = Image.createImage(conn.openInputStream());
                  alert = new Alert(title, "Delete Image?", image, AlertType.WARNING);
                  alert.addCommand(DELETE_COMMAND);
                  alert.addCommand(CANCEL_COMMAND);
              } catch (IOException ioe1) {
                  alert = new Alert("Image Delete",
                          "Selected file cannot be displayed as an image.",
                          null, AlertType.ERROR);
              } finally {
                  try {if (conn != null) conn.close();} catch (IOException ioe2) {}
              }
          } else if (c == FileSelector.CANCEL_COMMAND) {
              // Invoked when the user cancels a file selection
              alert = new Alert(title, "Image selection canceled.", null, AlertType.INFO);
          } else if (c == CANCEL_COMMAND) {
              // Invoked when the user has cancelled the delete of the image
              alert = new Alert(title, "Image delete canceled.", null, AlertType.INFO);
          } else if (c == DELETE_COMMAND) {
              // Invoked when the user has confirmed the delete of the image
              String fileurl = fs.getURL();
              FileConnection fc = null;
              try {
                  fc = (FileConnection)Connector.open(fileurl, Connector.WRITE, false);
                  fc.delete();
                  alert = new Alert(title,
                          "Image delete confirmed.", null, AlertType.CONFIRMATION);
              } catch (IOException ioe) {
                  alert = new Alert(title,
                          "Unable to delete image.", null, AlertType.ERROR);
              } finally {
                  try { if (fc != null) fc.close();} catch (IOException ioe2) {}
              }
          }
          alert.setCommandListener(this);
          display.setCurrent(alert, oldCurrent);
      }
  }

Since:
MIDP 3.0

Field Summary
static Command CANCEL_COMMAND
          A Command delivered to a listener to indicate that user has dismissed the FileSelector without selecting any file.
static int DIRECTORY_CREATE
          This constant value indicates that the purpose of the file selector is to choose the name for a directory the application will create.
static int DIRECTORY_SELECT
          This constant value indicates that the purpose of the file selector is to locate a directory.
static int LOAD
          This constant value indicates that the purpose of the file selector is to locate a file from which to read.
static Command OK_COMMAND
           The OK Command delivered to a command listener indicates that a file has been selected from FileSelector.
static int SAVE
          This constant value indicates that the purpose of the file selector is to locate a file to which to write.
 
Constructor Summary
FileSelector(java.lang.String title, int mode)
          Creates a FileSelector with the specified title and mode.
 
Method Summary
 void addCommand(Command cmd)
          FileSelector has two fixed, built-in Commands: OK_COMMAND and CANCEL_COMMAND.
 java.lang.String[] getFilterExtensions()
          Gets the file extensions set for this file selector.
 int getHeight()
          Gets the height in pixels of the displayable area in FileSelector that is used to render file or directory information without scrolling.
 int getMode()
          Sets whether this file selector is for loading from a file, for saving to a file, or for finding a directory.
 java.lang.String getURL()
          Gets the URL of the user selected directory and file.
 int getWidth()
          Gets the width in pixels of the displayable area in FileSelector that is used to render file or directory information without scrolling.
 javax.microedition.io.StreamConnection open(int mode, boolean timeouts)
          Creates and opens a StreamConnection to the URL in getURL.
 void removeCommand(Command cmd)
          FileSelector does not allow Commands to be removed.
 void removeCommandOrMenu(int placement)
          FileSelector does not allow Commands or Menus to be removed.
 void setCommand(Command cmd, int placement)
          FileSelector has two fixed, built-in Commands: OK_COMMAND and CANCEL_COMMAND.
 void setCommandLayoutPolicy(CommandLayoutPolicy policy)
          FileSelector does not allow setCommandLayoutPolicy() to be called.
 void setFilterExtensions(java.lang.String[] extensions)
          Sets the file extensions for this file selector to show only the files with the set extensions.
 void setMenu(Menu menu, int placement)
          FileSelector does not allow menus to be added.
 void setMode(int mode)
          Sets the mode of the file selector to one of LOAD, SAVE, DIRECTORY_SELECT or DIRECTORY_CREATE.
 void setURL(java.lang.String URL)
          Sets the selected directory and file for this file selector according to the given URL.
 
Methods inherited from class javax.microedition.lcdui.Displayable
getCommand, getCommandLayoutPolicy, getCommands, getCurrentDisplay, getMenu, getTicker, getTitle, invalidateCommandLayout, isShown, setCommandListener, setTicker, setTitle, sizeChanged
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

OK_COMMAND

public static final Command OK_COMMAND

The OK Command delivered to a command listener indicates that a file has been selected from FileSelector. The field values of OK_COMMAND are as follows:

The implementation displays OK_COMMAND to the user using an implementation-specific label. Setting the long or short labels MUST have no effect on the label presented to the user.

CANCEL_COMMAND

public static final Command CANCEL_COMMAND
A Command delivered to a listener to indicate that user has dismissed the FileSelector without selecting any file. The field values of CANCEL_COMMAND are as follows:

The implementation displays CANCEL_COMMAND to the user using an implementation-specific label. Setting the long or short labels MUST have no effect on the label presented to the user.

LOAD

public static final int LOAD
This constant value indicates that the purpose of the file selector is to locate a file from which to read.

Value 0 is assigned to LOAD.

See Also:
Constant Field Values

SAVE

public static final int SAVE
This constant value indicates that the purpose of the file selector is to locate a file to which to write. The file selector must also allow the user to create a new file name.

Value 1 is assigned to SAVE.

See Also:
Constant Field Values

DIRECTORY_SELECT

public static final int DIRECTORY_SELECT
This constant value indicates that the purpose of the file selector is to locate a directory.

Value 2 is assigned to DIRECTORY.

See Also:
Constant Field Values

DIRECTORY_CREATE

public static final int DIRECTORY_CREATE
This constant value indicates that the purpose of the file selector is to choose the name for a directory the application will create.

Value 3 is assigned to DIRECTORY.

See Also:
Constant Field Values
Constructor Detail

FileSelector

public FileSelector(java.lang.String title,
                    int mode)
Creates a FileSelector with the specified title and mode. If the value of mode is LOAD, then the file selector is for finding a file to be read. If the value of mode is SAVE, the file selector is for finding a file to write. If the value of mode is DIRECTORY_SELECT, then the file selector is for finding a directory. If the value of the mode is DIRECTORY_CREATE, then the file selector is for creating new directories.

Parameters:
title - The title of the dialog, or null if no title
mode - The mode of the dialog
Throws:
java.lang.UnsupportedOperationException - if the underlying system does not have a file system to support the use of this class
java.lang.IllegalArgumentException - if the mode is other than LOAD, SAVE, DIRECTORY_SELECT or DIRECTORY_CREATE.
See Also:
LOAD, SAVE, DIRECTORY_SELECT, DIRECTORY_CREATE
Method Detail

addCommand

public void addCommand(Command cmd)
FileSelector has two fixed, built-in Commands: OK_COMMAND and CANCEL_COMMAND. New Commands are not allowed on FileSelector, so this method will always throw IllegalStateException whenever it is called.

Overrides:
addCommand in class Displayable
Parameters:
cmd - the Command is ignored
Throws:
java.lang.IllegalStateException - always

setCommand

public void setCommand(Command cmd,
                       int placement)
FileSelector has two fixed, built-in Commands: OK_COMMAND and CANCEL_COMMAND. New Commands are not allowed on FileSelector, so this method will always throw IllegalStateException whenever it is called.

Overrides:
setCommand in class Displayable
Parameters:
cmd - the Command is ignored
placement - the placement is ignored
Throws:
java.lang.IllegalStateException - always

removeCommand

public void removeCommand(Command cmd)

FileSelector does not allow Commands to be removed.

Overrides:
removeCommand in class Displayable
Parameters:
cmd - the Command is ignored
Throws:
java.lang.IllegalStateException - always

removeCommandOrMenu

public void removeCommandOrMenu(int placement)

FileSelector does not allow Commands or Menus to be removed.

Overrides:
removeCommandOrMenu in class Displayable
Parameters:
placement - the placement is ignored
Throws:
java.lang.IllegalStateException - always

setMenu

public void setMenu(Menu menu,
                    int placement)

FileSelector does not allow menus to be added.

Overrides:
setMenu in class Displayable
Parameters:
menu - the Menu ignored
placement - the placement is ignored
Throws:
java.lang.IllegalStateException - always

getMode

public int getMode()
Sets whether this file selector is for loading from a file, for saving to a file, or for finding a directory.

Returns:
the mode of this FileSelector, one of: FileSelector.LOAD, FileSelector.SAVE, FileSelector.DIRECTORY_SELECT or FileSelector.DIRECTORY_CREATE.
See Also:
LOAD, SAVE, DIRECTORY_SELECT, DIRECTORY_CREATE, setMode(int mode)

setMode

public void setMode(int mode)
Sets the mode of the file selector to one of LOAD, SAVE, DIRECTORY_SELECT or DIRECTORY_CREATE.

Parameters:
mode - the mode for this file selector, one of FileDialog.LOAD, FileSelector.SAVE, FileSelector.DIRECTORY_SELECT or FileSelector.DIRECTORY_CREATE.
Throws:
java.lang.IllegalArgumentException - if an illegal file selector mode is used
See Also:
LOAD, SAVE, DIRECTORY_SELECT, DIRECTORY_CREATE, getMode()

getURL

public java.lang.String getURL()
Gets the URL of the user selected directory and file. If the user selected CANCEL_COMMAND, null is returned. The URLs passed to and returned by the FileSelector are formatted as fully qualified absolute file URLs [RFC3986].

Returns:
the URL of the currently selected directory and file, if the user has selected a file or directory with OK; otherwise null.

setURL

public void setURL(java.lang.String URL)
            throws java.io.IOException
Sets the selected directory and file for this file selector according to the given URL. This file becomes the default file, if it is set before the file selector is first set to visible. Specifying a hidden file maps to the behavior of the filesystem and native platform; for example if hidden files are shown because of a system wide user preference, then they are shown via FileSelector as well.

If supported by the filesystem, specifying a file that does not exist will result in creation of a new file by that name.

The directory and file names passed to and returned by the FileSelector are formatted as fully qualified absolute file URLs [RFC3986].

Parameters:
URL - the file being set; if null, then the default directory is the URL of the MIDlet suite's private storage directory.
Throws:
java.lang.IllegalArgumentException - if the URL is not a valid absolute file URL or is empty.
java.io.IOException - if the mode is LOAD and the URL refers to a file that does not exist.
java.io.IOException - if the mode is SAVE and the URL refers to a directory that does not exist or in which the application is not permitted to create files or refers to a file which exists as a directory.
java.io.IOException - if the mode is DIRECTORY_SELECT and the URL refers to a directory that does not exist.
java.io.IOException - if the mode is DIRECTORY_CREATE and the URL refers to a directory that does not exist or in which the application is not permitted to create directories or refers to a directory which exists as a file.
java.lang.SecurityException - if the URL references a directory or file that the MIDlet is not allowed to access.

setFilterExtensions

public void setFilterExtensions(java.lang.String[] extensions)
Sets the file extensions for this file selector to show only the files with the set extensions. The extension strings are file system specific. For example, "txt" or "xml".

Parameters:
extensions - the file extensions being set; if null or an empty array then no filtering will be done.

getFilterExtensions

public java.lang.String[] getFilterExtensions()
Gets the file extensions set for this file selector. The extension strings are file system specific: for example "txt" or "xml". The extension strings are file system specific: for example "txt" or "xml".

Returns:
the file extensions for this file selector; if no filters are in effect, an empty String array MUST be returned.

open

public javax.microedition.io.StreamConnection open(int mode,
                                                   boolean timeouts)
                                            throws javax.microedition.io.ConnectionNotFoundException,
                                                   java.io.IOException
Creates and opens a StreamConnection to the URL in getURL. This method is similar to Connector.open(getURL(), mode, timeouts). The application should use this method to access the content of the URL to avoid redundant access checks.

If JSR-75 is present, the StreamConnection returned SHOULD implement the javax.microedition.file.FileConnection. Applications can use the instanceof operator to determine if a FileConnection was returned.

Parameters:
mode - the access mode
timeouts - a flag to indicate that the caller wants timeout exceptions
Returns:
a StreamConnection supporting the requested mode.
Throws:
javax.microedition.io.ConnectionNotFoundException - If the target of the name cannot be found, or if the requested protocol type is not supported.
java.io.IOException - If some other kind of I/O error occurs.
java.lang.SecurityException - If access to the content is prohibited.

getWidth

public int getWidth()
Gets the width in pixels of the displayable area in FileSelector that is used to render file or directory information without scrolling. This displayable area only includes the area which displays the file or directory information. This area excludes any Title, Ticker, scrollbar, or commands that do no actually render the file or directory information.

Specified by:
getWidth in class Displayable
Returns:
width in pixels of the area available to display the given URL information
Since:
MIDP 3.0

getHeight

public int getHeight()
Gets the height in pixels of the displayable area in FileSelector that is used to render file or directory information without scrolling. This displayable area only includes the area which displays the file or directory information. This area excludes any Title, Ticker, scrollbar, or commands that do no actually render the file or directory information.

Specified by:
getHeight in class Displayable
Returns:
height in pixels of the area available to display the given URL information
Since:
MIDP 3.0

setCommandLayoutPolicy

public void setCommandLayoutPolicy(CommandLayoutPolicy policy)
FileSelector does not allow setCommandLayoutPolicy() to be called. Applications are not allowed to add/set Commands or Menus in FileSelector

Overrides:
setCommandLayoutPolicy in class Displayable
Parameters:
policy - the CommandLayoutPolicy is ignored
Throws:
java.lang.IllegalStateException - always
Since:
MIDP 3.0
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
MIDP3.0
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Send a comment or suggestionVersion 3.0 of Mobile Information Device Profile Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries. Copyright 2002-2009 Motorola Inc. Portions copyright 1993-2002 Sun Microsystems, Inc. and Motorola, Inc. All Rights Reserved.