PickleLauncher

PickleLauncher by Scott Smith (Pickle) Copyright (C) 2010-2011

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 require that all documentation is included. If the DejaVu font is not included then the license is not required.

Contributions

Patches and suggestions for improvment 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

misc

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.

Details for profile.txt

 # Global Settings
 targetapp=<name>       

typically the name of appliction the launcher will be loading. The name will show in the title, i.e PickleLauncher for MyApp.

 filepath=<path>        

this the initial path where the launcher should look for the input files. i.e. filepath=/mnt/sd/roms or filepath=roms

 # Command Settings
 About                  

commands are 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>

   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/sudo cpuset

   cmdarg=<argument>;<default>;<option label 0>;<option value 0>;....   

defines an argument with a default value and all possible values

     <argument>          

the flag string.

     <default>           

the index of the default value used for all entries

     <option lLabel>     

a string label to represent the value in the GUI

     <option value>      

a string value appended to the flag

     i.e. --setcpuspeed;0;200 Mhz;200;400 Mhz;400;600 Mhz;600

 # 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.

   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
 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

DETAILS for 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.