net.returnvoid.io

## Class DataLoader

- java.lang.Object
- - net.returnvoid.io.DataLoader

- Direct Known Subclasses:
    ColorPaletteLoader, ImageLoader

      public abstract class DataLoader
      extends java.lang.Object

  Abstract class for DataLoaders. DataLoaders will handle to load files from a specific type (e.g. images) from a specific folder. Currently doesn't support the automatic loading of files within sub-folders. The files are loaded "on demand" as they are tried to be read with the getCurrent() or any other get method. The class will handle to run through all files of the given type via methods (e.g. next()) or on a KeyEvent (keyPressed with a pre-defined / defined key / keycode).
  Author:
    Diana Lange

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `COLOR_PALETTE` File type: COLOR_PALETTE (.color.json)
    `static int` | `CSV` File type: CSV (.csv)
    `protected int` | `fileIndex` The index of the current loaded file.
    `protected java.lang.String[]` | `filePaths` Contains the absolut paths to files which will be loaded.
    `static int` | `IMAGE` File type: Image (.jpg, .gif, .png, ...)
    `static int` | `JSON` File type: JSON (.json)
    `protected processing.core.PApplet` | `parent` The PApplet object (KeyEvents will be regulated by it).
    `static int` | `SHAPE` File type: Shape (.svg)
    `static int` | `TEXT` File type: Text (.txt)
    `protected int` | `type` The type of this object, e.g.
    `static int` | `XML` File type: XML (.xml, .htm, .html)

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `DataLoader(processing.core.PApplet parent, java.lang.String folderPath, java.lang.String folderName)` Builds the DataLoader and registers the KeyEvent to the parent (PApplet).

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `DataLoader` | `disableKeys()` Disable the automatic key events of this object.
    `DataLoader` | `enableKeys()` Enables the automatic key events of this object.
    `abstract java.lang.Object` | `first()` Loads (if necessary) and returns the first file of the given folder.
    `abstract java.lang.Object` | `get(int index)` Loads (if necessary) and returns the file with the given index.
    `abstract java.lang.Object` | `getCurrent()` Loads (if necessary) and returns the current file.
    `java.lang.String` | `getFileName()` Gets the file name of the current file.
    `java.lang.String` | `getFileName(boolean removeFileType)` Gets the file name of the current file.
    `java.lang.String` | `getFileName(int index)` Gets the file name of the file with the given index.
    `java.lang.String` | `getFileName(int index, boolean removeFileType)` Gets the file name of the file with the given index.
    `java.lang.String` | `getFolder()` Returns the name of the folder of whom the files will be loaded.
    `java.lang.String` | `getLoadingDirectory()` Returns the path of the directory where all files of the given type will be loaded.
    `java.lang.String` | `getPath()` Returns the path to the loading folder.
    `void` | `keyEvent(processing.event.KeyEvent evt)` A function for handling the KeyEvent.
    `abstract java.lang.Object` | `last()` Loads (if necessary) and returns the last file of the given folder.
    `abstract java.lang.Object[]` | `loadAllFiles()` Loads all files (if not loaded yet) and returns them all.
    `abstract java.lang.Object` | `loadFile(int index)` Loads a file with the given index and returns it.
    `protected java.lang.String[]` | `loadPaths(int type)` Loads all the absolute paths for all valid files defined by the given type in the set folder.
    `protected java.lang.String[]` | `loadPaths(java.lang.String[] dataTypes)` Loads all the absolute paths for all valid files defined by the given dataTypes array in the set folder.
    `abstract java.lang.Object` | `next()` Loads (if necessary) and returns the next file of the given folder.
    `abstract java.lang.Object` | `nextRandom()` Loads (if necessary) and returns the next random file of the given folder.
    `abstract java.lang.Object` | `previous()` Loads (if necessary) and returns the previous file of the given folder.
    `DataLoader` | `resetKeySettings()` Resets the key settings for the KeyEvents to its default.
    `DataLoader` | `setIndex(int index)` Sets the current element.
    `DataLoader` | `setIndex(java.lang.String filename)` Sets the current element.
    `DataLoader` | `setKey(java.lang.String which, char key)` Links a certain method call (e.g. next()) with a certain key (e.g.
    `DataLoader` | `setKey(java.lang.String which, int keyCode)` Links a certain method call (e.g. next()) with a certain keyCode (e.g.
    `int` | `size()` Returns the number of files within the given folder.
    `DataLoader` | `update()` Re-Loads all the absolute paths for all valid files defined by the given type in the set folder.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### parent

          protected processing.core.PApplet parent

      The PApplet object (KeyEvents will be regulated by it).

    - #### filePaths

          protected java.lang.String[] filePaths

      Contains the absolut paths to files which will be loaded.

    - #### type

          protected int type

      The type of this object, e.g. IMAGE.

    - #### fileIndex

          protected int fileIndex

      The index of the current loaded file.

    - #### IMAGE

          public static final int IMAGE

      File type: Image (.jpg, .gif, .png, ...)
      See Also:
        Constant Field Values

    - #### TEXT

          public static final int TEXT

      File type: Text (.txt)
      See Also:
        Constant Field Values

    - #### CSV

          public static final int CSV

      File type: CSV (.csv)
      See Also:
        Constant Field Values

    - #### JSON

          public static final int JSON

      File type: JSON (.json)
      See Also:
        Constant Field Values

    - #### SHAPE

          public static final int SHAPE

      File type: Shape (.svg)
      See Also:
        Constant Field Values

    - #### XML

          public static final int XML

      File type: XML (.xml, .htm, .html)
      See Also:
        Constant Field Values

    - #### COLOR_PALETTE

          public static final int COLOR_PALETTE

      File type: COLOR_PALETTE (.color.json)
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### DataLoader

          protected DataLoader(processing.core.PApplet parent,
                               java.lang.String folderPath,
                               java.lang.String folderName)

      Builds the DataLoader and registers the KeyEvent to the parent (PApplet).
      Parameters:
        `parent` - A PApplet object.
        `folderPath` - A absolute path to the folder. Example: "C:\\" is the folderPath and "data " is the foldername then the files of the folder located at " C:\\data\\" will be loaded. Make sure to escape the backslashes in the path in the shown way. If folderPath is null, the sketch location will be used to set this path.
        `folderName` - Folder containing files (not null). This folder should at least contain one file. The given folder should be a sub-folder of folderpath or a relative path to folderPath. e.g. "C:\\data" is the folderpath and "..\\temp" is the foldername then "C:\\temp\\" will be the location where the files will be loaded. Make sure to escape the backslashes in the path in the shown way.

  - ### Method Detail

    - #### getFolder

          public java.lang.String getFolder()

      Returns the name of the folder of whom the files will be loaded.
      Returns:
        The folder name (preset folder name: 'data').

    - #### getPath

          public java.lang.String getPath()

      Returns the path to the loading folder.
      Returns:
        The path to the folder containing the files which will be loaded.

    - #### getLoadingDirectory

          public java.lang.String getLoadingDirectory()

      Returns the path of the directory where all files of the given type will be loaded.
      Returns:
        The absolute path to the loading directory.

    - #### loadFile

          public abstract java.lang.Object loadFile(int index)

      Loads a file with the given index and returns it. Prevent out of bounds exception by checking the range with the size() method. Even if the files has been loaded before this will induce a load again. This might be useful if the content of the file has been changed in the meen time.
      Parameters:
        `index` - The index of the file which should be loaded.
      Returns:
        The loaded file.

    - #### loadAllFiles

          public abstract java.lang.Object[] loadAllFiles()

      Loads all files (if not loaded yet) and returns them all.
      Returns:
        The object of the file.

    - #### nextRandom

          public abstract java.lang.Object nextRandom()

      Loads (if necessary) and returns the next random file of the given folder.
      Returns:
        The object of the file.

    - #### previous

          public abstract java.lang.Object previous()

      Loads (if necessary) and returns the previous file of the given folder. The order of the files is set by their file names. Previous will load the file previous to the current file concerning their names.
      Returns:
        The object of the file.

    - #### next

          public abstract java.lang.Object next()

      Loads (if necessary) and returns the next file of the given folder. The order of the files is set by their file names. Previous will load the file previous to the current file concerning their names.
      Returns:
        The object of the file.

    - #### first

          public abstract java.lang.Object first()

      Loads (if necessary) and returns the first file of the given folder. The order of the files is set by their file names.
      Returns:
        The object of the file.

    - #### last

          public abstract java.lang.Object last()

      Loads (if necessary) and returns the last file of the given folder. The order of the files is set by their file names.
      Returns:
        The object of the file.

    - #### getCurrent

          public abstract java.lang.Object getCurrent()

      Loads (if necessary) and returns the current file.
      Returns:
        The object of the file.

    - #### get

          public abstract java.lang.Object get(int index)

      Loads (if necessary) and returns the file with the given index. Prevent out of bounds exception by checking the range with the size() method.
      Returns:
        The object of the file.

    - #### setIndex

          public DataLoader setIndex(int index)

      Sets the current element.
      Parameters:
        `index` - The index of the element which should be the current element. Index is in range of [0, size()).
      Returns:
        The current DataLoader object.

    - #### setIndex

          public DataLoader setIndex(java.lang.String filename)

      Sets the current element.
      Parameters:
        `filename` - The name of the file which should be the current element.
      Returns:
        The current DataLoader object.

    - #### resetKeySettings

          public DataLoader resetKeySettings()

      Resets the key settings for the KeyEvents to its default. The default is:
      Arrow left = previous
      Arrow right = next
      Arrow up = first
      Arrow down = last
      Tabulator = next random
      Returns:
        The DataLoader object.

    - #### size

          public int size()

      Returns the number of files within the given folder.
      Returns:
        The number of accessible files.

    - #### keyEvent

          public void keyEvent(processing.event.KeyEvent evt)

      A function for handling the KeyEvent. Is controlled by the parent (PApplet).
      Parameters:
        `evt` - The object containing the information about the KeyEvent.

    - #### disableKeys

          public DataLoader disableKeys()

      Disable the automatic key events of this object.
      Returns:
        The DataLoader object.

    - #### enableKeys

          public DataLoader enableKeys()

      Enables the automatic key events of this object.
      Returns:
        The DataLoader object.

    - #### setKey

          public DataLoader setKey(java.lang.String which,
                                   int keyCode)

      Links a certain method call (e.g. next()) with a certain keyCode (e.g. KeyEvent.VK_RIGHT).
      Parameters:
        `which` - A String representing the method which should be linked to the keyCode. Possible values: \ "previous\", \"next\", \"first\", \"last\", \"random\".
        `keyCode` - The keyCode for the key which should be used for the given function.
      Returns:
        The DataLoader object.

    - #### setKey

          public DataLoader setKey(java.lang.String which,
                                   char key)

      Links a certain method call (e.g. next()) with a certain key (e.g. \'n\').
      Parameters:
        `which` - A String representing the method which should be linked to the keyCode. Possible values: \ "previous\", \"next\", \"first\", \"last\", \"random\".
        `key` - The char containing the key which should be used for the given function.
      Returns:
        The DataLoader object.

    - #### getFileName

          public java.lang.String getFileName(int index,
                                              boolean removeFileType)

      Gets the file name of the file with the given index. Prevent out of bounds exception by checking the range with the size() method. Removes the file extension if wanted, i.e. returns \ "myimage\" instead of \"myimage.jpg\".
      Parameters:
        `index` - The index of the file of which the name should be returned.
        `removeFileType` - True if the file extension should be removed.
      Returns:
        The file's name.

    - #### getFileName

          public java.lang.String getFileName(int index)

      Gets the file name of the file with the given index. Prevent out of bounds exception by checking the range with the size() method.
      Parameters:
        `index` - The index of the file of which the name should be returned.
      Returns:
        The file's name.

    - #### getFileName

          public java.lang.String getFileName()

      Gets the file name of the current file.
      Returns:
        The file's name.

    - #### getFileName

          public java.lang.String getFileName(boolean removeFileType)

      Gets the file name of the current file. Removes the file extension if wanted, i.e. returns \ "myimage\" instead of \"myimage.jpg\".
      Parameters:
        `removeFileType` - True if the file extension should be removed.
      Returns:
        The file's name.

    - #### update

          public DataLoader update()

      Re-Loads all the absolute paths for all valid files defined by the given type in the set folder. All already loaded (and buffered) files will have to be reloaded afterwards. Update might get called after a change in the directory has been made (e.g. a file has been removed). The current object will still be the same after update() if the file still exits in the directory.
      Returns:
        The DataLoader object.

    - #### loadPaths

          protected java.lang.String[] loadPaths(int type)

      Loads all the absolute paths for all valid files defined by the given type in the set folder.
      Parameters:
        `type` - A file type (DataLoader.IMAGE, DataLoader.Text, ...)
      Returns:
        The absolute paths to the files.

    - #### loadPaths

          protected java.lang.String[] loadPaths(java.lang.String[] dataTypes)

      Loads all the absolute paths for all valid files defined by the given dataTypes array in the set folder.
      Parameters:
        `dataTypes` - An array containing the valid extension types in form of e.g. \".jpg\"
      Returns:
        The absolute paths to the files.