Difference between revisions of "PickleLauncher"

Latest revision as of 12:08, 12 October 2011

Summary

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

Sourceforge Project Page: http://sourceforge.net/projects/picklelauncher/

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. The launcher will use the information given and scan the current path for files that can be launched with the target application and present them to the user. The user can modify options (passed by argument flags) for all entries or for one specific entry. When an entry is selected the user can launch the file. PickleLauncher constructs a command line script which is set to trigger once the launcher is quit. Once the user quits the target application the script has execution command to reload PickleLauncher. The user can choose to select, edit, or quit PickleLauncher.

Source and Project Information

PickleLauncher source code is released under gplv3 see COPYING.txt for license details. Access to a copy of the source can be found on the sf.net project page: http://sourceforge.net/projects/picklelauncher/ 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. 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 the following link for license details:

http://github.com/mtorromeo/gmenu2x/blob/master/COPYING

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 through click-able buttons. The touchscreen can also select entries directly through the entry list.

Buttons on Left-hand Side

<       : one up
>       : one down
<<      : page up
>>      : page down
U       : one directory level up
D       : one directory level down
Z       : switch zip mode from extraction of all files to only the selected file

Buttons on Right-hand Side

Mode Select Entry/Browse

Edit Item (2) : 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    (1) : 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    (2) : selects the argument for the command or extension and reads in possible values for selection.
Back      (1) : returns to the entry/browse selection mode

Mode Select Argument Value*

Set       (3) : 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   (2) : the selected value will be set for all entries. Current default is marked by the star character *.
Back      (1) : Returns to the argument selection mode

Common

Quit      (0) : quits the launcher

Features

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(s). If a file inside the zip is chosen then the launcher will extract the file(s) 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, so if the launcher has an error on the next time PickleLauncher runs the files will be deleted.

Configuration File: 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. It must be constructed by hand before PickleLauncher can be of use.

Global Settings

These are the settings that are global and required. These must be included.

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 or ./. In general it can look like this: filepath=/mnt/sd/roms or filepath=roms or filepath=./

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.

Example

<CPU Speed>         
 cmdpath=/usr/bin/sudo cpuset
 cmdarg=--clock;0;500 Mhz;500;700 Mhz;700;...
 cmdarg=--memory;1;10 Clk;5;12 Clk;12;...
results in:  /usr/bin/sudo cpuset --clock 500 --memory 12

Details

<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 application is executed. i.e cmdpath=/bin/to/somewhere/cpuset

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

This defines an argument with a default value and all possible values. Here is an explanation 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

Examples

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

Configuration File: config.txt

NOTE: PickleLauncher has built in defaults, it is suggested that you use these values. But if something isn't quite the way you want, such as colour, 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.

Adding a skin

PickleLauncher can be skinned by placing graphics in an /images directory, either inside the PND or in the applicable /appdata location. Below is a list of filenames PickleLauncher may look for, and their equivalent text labels.

Image file	Text label
background.png	n/a
button_back.png	Back
button_cfg_app.png	unknown
button_cfg_item.png	Edit Item
button_dirdn.png	D
button_dirup.png	U
button_launch.png	Select
button_onedn.png	>
button_oneup.png	<
button_pagedn.png	>>
button_pageup.png	<<
button_quit.png	Quit
button_set_all.png	Default
button_set_one.png	Set
pointer.png	n/a

For reference, skinned PickleLauncher apps include PanPlayer, Snes9x4p, and GnuBoy.