PickleLauncher

Summary

PickleLauncher is meant to a simple frontend for autodetecting and configuring command line based applications that might have different input files, like emulators.

How it works

PickleLauncher looks for its configuration from the config.txt and profile.txt. profile.txt specifies location, file types, commands, arguments, and entries. config.txt contains options for the application gui and input.

License and Redistribution

PickleLauncher source code is released under gplv3 see COPYING.txt for license details. If you redistribute I request (but not require) that all documentation is included. If the DejaVu font is not included then the license is not required.

Contributions

Patches and suggestions for improvement are welcome

References

DejaVu font is Copyright (C) by Bitstream Vera Fonts (if included) see "DejaVu Fonts License.txt" for license details
Zip support uses minizip by Gilles Vollant and Mathias Svensson see "MiniZip64_info.txt" for license details
Portions of the exec support was based on Gmenu2x by Massimiliano Torromeo which is released under gplv2 see http://github.com/mtorromeo/gmenu2x/blob/master/COPYING for license details

Library Dependencies

zlib
SDL
SDL_ttf
SDL_image

Controls

PANDORA/PC

one up : up
one down : down
page up : left
page down : right
dir up : left shoulder
dir down : right shoulder
quit : escape
launch/select : enter

GP2X/WIZ/CAANOO

one up : up
one down : down
page up : left
page down : right
dir up : left shoulder
dir down : right shoulder
quit : select
launch/select : start

Mouse and Touchscreen

All devices that support it can do all controls through the screen. The buttons on the left do the following from top to bottom:

< : one up
> : one down
<< : page up
>> : page down
U : one directory level up
D : one directory level down

Buttons on the right side from top to bottom

Mode Select Entry/Browse
Edit Item : will open a list to select an command or argument that then can be selected and the assigned value changed. Directories are highlighted in red and files are black.
Launch : will launch the current item if an input file, if a directory is selected the selector will go down into the folder. If dirs exepath is defined then directories will become launchable and editable.

Mode Select Argument

Select : selects the argument for the command or extension and reads in possible values for selection.
Back : returns to the entry/browse selection mode

Mode Select Argument Value

Set : the selected value will be set for this entry. This will trigger a custom entry to be saved in the profile.txt. Current selected value is in red.
Default : the selected value will be set for all entries. Current default is marked by the star character *.
Back : eturns to the argument selection mode

Common :
Quit : quits the launcher

Zip Support

Zips are treated like a folder. When selected the launcher will read the zip and display any contents that match a defined extenstion. If a file inside the zip is chosen then the launcher will extract all content from the zip into the configurable zip path. Upon quiting the launcher will delete any extracted files from the zip path. Extracted files are recorded in the ziplist.txt.

profile.txt

profile.txt describes the behavior of PickleLauncher. It offers several settings that can be configured to more precisely set how the launcher should behave and interact with the user.

Global Settings

These are the settings that are global and required. Those musn't be omitted.

targetapp=<name>

<name> specifies the name of the application to use. This name will show in the title. If eg <name> is set to MyApp' the title will read "PickleLauncher for MyApp".

filepath=<path>

<path> specifies the initial path where the launcher should look for the input files. A good starting point (for the Pandora) is probably /media. In general it can look like this: filepath=/mnt/sd/roms or filepath=roms.

Command Settings

Commands can be any binary or script with its own arguments (1 or more) that will be run prior to running the target application.

<command name>

Identifies the beginning of a command and its name for display in the GUI, i.e <CPU Speed>. Inside those blocks additional things have to be listed:

cmdpath=<path>

This is the path to the binary command that will be run before the target appliction is executed. i.e cmdpath=/bin/to/somwhere/cpuset

cmdarg=<argument>;<default>;<option label0>;<option value0>;<option label1>;<option value1>;...

This defines an argument with a default value and all possible values. Here is an explainaintion of what the things are supposed to mean:

<argument>: Flag string
<default>: Index of the default value used for all entries (starting with 0)
<option label>: String label to represent the value in the GUI
<option value>: String value appended to the flag

A complete argument can look like this: --setcpuspeed;0;200 Mhz;200;400 Mhz;400;600 Mhz;600 It will add the argument --setcpuspeed to the program specified by cmdpath and as default have the first entry, which has the label 200 MHz and means a parameter of 200 selected.

Extension Settings

 # Extension Settings
 About                   : extensions are the key component to configuring the launcher. They link
                           files identified by extensions to a target application that will run them.

 [dirs]                    special case that will consider folders to be treated as launchable files
                           if the exepath is defined. This mode will also disable browsing so the
                           launcher will be locked into the defined filepath. The exepath can be 
                           left empty and [dirs] can be used for just the blacklist option to hide
                           folders.

 [ext]                     : this identifies the file type to look for. All following options will be
                             associated with this extension only. File types can be chained.
   exepath=<path and binary : this is the path to the target application's binary file used by this  
                              extension
     i.e. exepath=/mnt/sd/games/mygame/superemu or exepath=./superapp

   blacklist=<list : this is a list of files that should not show up in the entry list (can be empty)
     i.e. blacklist=somerom.bin,anotherrom.bin

   extarg=<argument>;<default>;<option Label 0>;<option Value 0>;....   : is used to specify 
                                                          arguments for the files with the extension.
     <argument>               : the flag string.
     <default>                : the index of the default value used for all entries
     <option label>           : a string label to represent the value in the GUI
     <option value>           : a string value appended to the flag
     There are special strings for the default value:
       %filename%             : copies the entry filename to be used with the agrument flag
       %na%                   : specifes that the argument shouldnt be used and expects the user
                                to put an value for the entries that need it.
       i.e extarg=-sound;1;11 Khz;11;22 Khz;22  OR
           extarg=-config;0;%na%;config.cfg     OR
           extarg=-rom;0;%na%;%filename%

   argforce=<path>;<argument index>;<new value>  : this will assign the new value specfied to all 
                                                   entries detected in the path given.
     <path>
     <argument index>
     <new value>
   i.e argswap=./exps/are/here/,1,exp1.rom

Custom Entries Settings

 # Custom Entries Settings
 About                     : Entries are used to store custom values for any detected entry. 
                             Normally these never need to be manually created as the launcher 
                             will do it. Although options like alias need to be inputted by the user.
 {<path and filename>;<alias>}
   <path and filename>         : the path and filename that the entry should be applied.
   <alias>                     : replaces the filename as the string name that will be displayed in 
                                 the GUI.
   entrycmds=<values>          : a list of values to be used to set for the command arguments 
                                 according to the order that commands are defined in the profile.txt.
     i.e entrycmds=1
   entryargs=<values>          : a list of values to be used to set for the extension arguments 
                                according to the order that arguments are defined in the profile.txt.
     i.e entryargs=0;3;2

Example

This is the profile.txt file that is used with snes9x4p to allow support for the common known rom formats. It does set the default file path to /media/ and supports the file extensions sfc, smc, 7z as well as zip. For each the script ./snes.sh will be executed and the filename of the selected file added. This is just the defconfig file and will be copied into appdata to be replaced by the user config file in which the last filepath will automatically be stored when exiting the program.

# Global Settings
filepath=/media/

# Extension Settings
[sfc;smc;7z;zip]
exepath=./snes.sh
arg=,%filename%

# Custom Entries Settings

config.txt

NOTE: picklelauncher has built in defaults, it is suggested that you use these values. But if something isnt quite the way you want, like color use this file to customize the gui.

See the config.txt for details. If you do not see a config.txt run the launcher once and one will be generated.