Lettuce Homepage

Syntax Highlighter

Lettuce features a fully customisable syntax highlighter. If you are not happy with the initial scheme you can go to Edit->settings and select your own colours.

User-definable parameter hints

Whenever a user types an opcode Lettuce will automatically display parameters for that opcode.



If users want to define their own parameter hints they can do so from the settings dialog.






Code Repository

Users can save snippets of code to the code repository and insert them as they need them. This saves valuable time and prevents the need to keep re-typing the same code over and over again.








Breakpoint Editor

The breakpoint editor is useful for creating quick envelope sketches. Users can launch the editor by hitting Ctrl+B, or by accessing it from the menu.



To open a particular envelope of ftable just make sure the text caret is on the correct line
and hit Ctrl+B or access the editor from the tool bar.





Command Prompt

If you would rather not use the play/stop button to run your .csd file or you wish to use Lettuce
with an alternative version of Csound you can click the Command Prompt button. Users can set their own command prompt in teh suers ettings. This allows users to move away from Dos and use MSYS or any other command prompt if they wish.





Calculator

The calculator can be accessed from the tool bar or by clicking on the Calculator button. By default Lettuce attempts to open the default windows calculator. If users wish to specify their own calculator/plotter to use they can do so by choosing it from the settings dialogs.

Soundfile Player

User can display the sounfile player by going to View->Sound file player. The player will appear with a combo box listing all the files that are in the current csound file. Users can then select the file they want to hear and press play. Users can specify the default playback options from teh setting windows.

New File Template

In the settings dialog you can choose the default text that Lettuce will open whenever a user opens a new file. This file is only used as a template and will not be overwritten unless you wish to do so. The file appears as "Untitled.csd"





Context Sensitive Help

Users can access the help manual from the tool bar. Lettuce also features context sensitive help so if the text caret on an opcode and the users hits F1 the Csound help manual will open at that page.





Batch Import of orc/sco files

Lettuce only works with unified csound files, csd. If users would like to convert previous sco/orc files to csd they may do so by clicking batch import from the file menu.





Browse for sound files

By right-clicking on the editor users can browse for a sound file to use in their code. Selecting the sound file you want to use from the select dialog will result in the full path for that sound file be entered to the code.





Error Tracking

By clicking on an error generated by Csound Lettuce will automatically direct you to the error in you file by highlighting the offending line.



This feature is still very much under development and at present only works when Csound quotes the erroneous string which caused the error. For more details check out the known issues sections.





Toggling between orc/sco files

Users can quickly toogle between orc/sco files by pressing Ctrl+Tab or by using the toggle button which appears to the right of the timer once an orc or sco file is loaded. In order to toggle between file the files must have the same bass name, i.e., test.orc test.sco




Building a simple standalone application.

Lettuce allows users to create standalone Windows programs from their csd files. Standalone GUI applications can only be built using .csd files. To build a simple standalone application go to the very top of the .csd file, before any Csound tags, and add the following text:

<Lettuce>
;form "Caption" width, height
form "Simple Application " 150, 70
</Lettuce>

The first line is a lettuce tag. This ensures that other editors can parse the csd file without any problems. All the GUI code should be kept between these tags. The next line is a comment so it's not necessary to add it but it's probably a good idea to do so until you are more familiar with each components parameters. The second line tells the Lettuce compiler to build a GUI form with a caption 'Simple Application' with a height of 150 pixels and a width of 70 pixels. If users want to force the main window to appear FULL SCREEN, they can pass -1 to both the height and width parameter. In order to run the application you must run the custom compiler which builds the application. To run the compiler hit the red 'C' compiler button from the tool menu.

If you do not receive any errors your new application will launch and you should see something like this,



From the file menu of your new application you can start/stop your Csound patch as well as exit the program. You can also view a text window which displays the Csound output. If you do not want users to be able to activate this feature you can type the following into the top of your csd file:

disable stdout


Adding controls

GUI controls can be added to your application to allow users to control different aspects of your instrument. The text for the controls as with the -form tag must be kept above the <CsoundSynthesizer> tag in the .csd file. In all of the control components, i.e., buttons, scrollbars, checkbox's and comboboxe's one must specify a channel name. This channel name is then used in the .csd file to identify the GUI control it's to communicate with. For example a quick volume control could be implemented like this:

instr 1
kval0 chnget "volume"
a1 oscil 10000, 220, 1
out a1*kval0
endin

where "volume" is the name specified after the GUI-control flag. It could be a scrollbar for example:

scrollbar "volume", 100, 17, 10, 10, "vertical", 0, 0, 100, 50

Once Csound starts running it will constantly check to see what value is being sent on the channel named "volume". When users move the scrollbar kval0 will be updated to reflect the movement made, thus allowing users to control their Csound instruments with GUI controls.

Below is a list of the available GUI components.


Button:

button "Name", width, height, top, left, "OnCaption", "OffCaption"

"OnCaption" and "OffCaption" are given to change the text of the button when a user presses it. If you chose to have the same name for each caption the button will act as a trigger rather than an on/off switch.

ScrollBar:

scrollbar "Name", width, height, top, left, "kind", label, min, max, initVal

"kind" will be either "Vertical" or "Horizontal", case sensitive. 'Label' will be either 0 or 1. If you specify 1 then a label will appear beside the scrollbar showing the current values that the scrollbar is outputting. Min and max are the minimum and maximum values of the scrollbar. initVal is the value the scrollbar will be initialised to. Note that csound will not recieve this intialisation value until the user clicks on the scrollbar so users will need to intialise krate values in their csound instruments themselves.


ComboBox:

combobox "Name", width, height, top, left, initVal, "itemCaption", "itemCaption" ...

"ItemCaption" is the string that appears in the ComboBox. One can specify as many items as they want. The first item, which the comboBox defaults to is valued at 0. initVal initialises the combobox to a aprticulat items. Counting begins from 0. Any time a user changes the value of a combo box the index of the new item is sent to Csound.


CheckBox:

checkbox "Name", width, height, top, left, initVal, "Caption"

initVal is a value, 0 for un-checked, 1 for checked. "Caption" is the caption that appears alongside the checkbox. When the checkbox is checked it is valued at 1, when not checked it's valued at 0.



OpenDialog:

opendialog soundinVar

This tag adds an Open-menu and OpenDialog to ones application providing users with a way to open and work with different sound files on the fly. "SoundinVar" is the name of the output variable to your soundin opcode, for example ksound in the following code:

ksound soundin "c:/test.wav"

For now only one sound file can only be open at a time and sound files should only be opened while Audio is off. This feature is quite limited but if the interest is there it can be extended in the future.


GroupBox:

groupbox "Caption", width, height, top, left, "colour"

A groupbox provides a container for controls. Caption is the name given to the frame. Frames can be useful for organising controls into different sections. "colour" can be specified to give a different colour. A list of colours can be found here.

panel "Caption", width, height, top, left, "colour"

A panel is a basic frame. Controls can be placed on them or they can be used to add some colours to your application. Caption is the name given to the panel. Names appear in the centre of the panel. If you do not wish to have the name appear leave it blank between double quotes.A list of colours can be found here.

Label:

label "Caption", width, height, top, left, "colour"

Useful for adding miscellaneous text to ones applications. A list of colours can be found here.

Image:

image "filename.bmp", width, height, top, left

"Filename.bmp" is the name of the bitmap to be used, including the .bmp extension. If the bitmap is not in the same directory as the application you will need to specify the full path.

aboutbox "caption", width, height
<abouttext>
Example text goes in here between the
starting tag and the end tag, by the way
this text can appear anywhere between
the Lettuce tags, it normally looks best at
the end of the other GUI code
</abouttext>

This tag create a new menu command, 'About' that will display whatever is passed between the <abouttext> and </abouttext> tags. Users may find it useful to provide help and information for their appications.

Colours:

This is a list of valid colours you can pass to label and frame. Remember to use the correct case.

Red
BtnFace
Blue
DkGray
Fuchsia
Gray
Green
Lime
LtGray
Maroon
Green
Navy
Olive
Purple
Olive
Black
Silver
Teal
Purple
White
Yellow
Aqua



Acknowledgments

First and foremost I wish to express my sincere thanks to Victor Lazzarini for his help on this project. I also wish to thank all the people on the Csound and SynEdit mailing lists for their support and patience in dealing with my many emails. Finally I want to say a big thank you to all those involved in the development of Csound 5 and particularly the host API which allows users the opportunity to harness the power of Csound in their own software.



Development

Lettuce is being developed with Borland's C++ Builder. The pseudo compiler that creates the standalone GUI's was also developed with C++ Builder however I have recently started looking at MinGW and wxWidgets as a viable alternative. If I do get around to doing this it will mean that I can at least start porting the 'compiler' to different platforms. Apart from native Windows code Lettuce also uses the SynEdit and TSynAnySyn VCL components.



Known Issues

Below are a list of things that need work. If you notice any bugs please let me know, and if possible let me know exactly what it was that caused the problem.

- Users can run an instrument that contains an fltk opcode but if they try to run it a second time it will crash. The same thing happens when running standalone application.
- The stop/play button sometimes causes a crash if users stop a performance just as the Csound performance is going to stop itself anyway. I should have this issue sorted soon, for now if there are only a few moments left in your performance just let it finish to the end rather than stop it with a second to go.
- If you wish to distribute your standalones you must ensure that users have the same version of csound installed that Lettuce uses. If you like you can bundle Csound with your application.
- The breakpoint editor still needs work. I did not intend to include it at all only for I found it useful for quick sketches and thought others might too. I haven't had time to really develop a good bp editor so if anyone out there wants to help finish it let me know. It's possible to open a function table by clicking on the ftable line of code and opening the bp editor, the one problem for now is that the ftable code has to begin at the very start of the line, i.e., no leading white space. As of yet there is now way to normalise the output between a negative and positive number, this can be done afterwards manually.
- With regards clicking on an error message, this only works when Csound quotes the offending string. Often the line numbers generated by the Csound output are incorrect but Lettuce will still guide you to the correct line regardless, so long as Csound quotes the erroneous string. I will try to update this feature soon as I believe it's could be an important learning tool for students.


Change Log


changes made for version1.3.9
-Added support for multiple pages, Ctrl+Tab to toggle through them
-Added f5 shortcut to refresh soundfile list and f8 is now compile shortcut
-Added X and Y position parameters to About Box and Form
-Added error notifications for syntax error in Lettuce GUI code
-Soundfile player is now a floating form rather than a tool bar
-file path gets updated to reflect each newly opened file, fixes 'unable to open file' errors
-fixed timer bug
-installer will no longer overwrite previous settings files
-added support for both Csound5 precision types

changes made for version1.3.8

-fixed compiler problem with short csd files
-users can now pass -1 size flags to their form tags to create a full window app
-added new <abouttext> and </abouttext> tags to help format about text better, more details above

changes made for version 1.3.7

-added CsOptions dialog to standalones so that users can change the default options
-added aboutbox dialogue so developers can add instructions or information about their instruments
-aligned csound output and about boxes in standalones, no longer appears on top of main window!

changes made for version 1.3.6

-fixed 'save as' problem, using save as will now also populate the recent files list
-fixed initialisation issue on restarting standalones, initial init value will be overridden
by any user changes made during performance.

changes made for version 1.3.5

-fixed file open bug
-updated version number

changes made for version 1.3.4

- increasing the total number of items allowed for combo boxes.
- the pseudo 'compiler' code has been rewritten due to lack of support for WinAPI functions on   Win ME/9x
- added initialisation parameter to scrollbar, combobox and checkbox whose values are now sent   first at i-time and again once the control is active.
- Added initialisation values for GUI components
- added 'panel' to csound.ini keywords
- adding correct entries for GUI controls in code hint popups
- users can now open soundfiles from the open menu
- Added integrated Csound media player with a play scrubber slider, Lettuce provides an   interface for soundfile.csd which is the file playing back the track.
- Added default playback device option for soundfile player, default is -odac
- f5 is now 'refresh' soundfiles and f8 is compile  
- Added checkbox for 'displaying message' from soundplayer in the main message window or not
- added automation to scrollbar for playback (needs work)
- No need to save prior to running csound, Lettuce runs csound with the current file so
  changes can be made and heard without having to save first
- Lettuce now stores user preference for line Numbers and View Sound File player
- Recent files will now show most recent file opened in current session
- Fixed close command from main file menu
- Made C:\Windows\system32\cmd.exe default command prompt for new users..
- added option to keep dos window open after running an fltk instrument
- added prompt to overwrite on saving....
- made changes to button control. If the users specifies the same caption for both on and off
  the button acts as a reset button, i.e, it sends a 1 and a moment later a 0. If the users
  specifies two different cpations it acts as a switch. Examples can be found on the homepage.

changes made for version 1.3.3:

-fixed auto-save on compile
-added basic fltk support. Users can run fltk instruments, although a dos window will also appear... at least it's better than a crash!
-fixed error when users try to close a standalone that contained errors in instrument


changes made for version 1.3.2:

-Added several keyboard shortcuts:
f9: Run/Stop Csound
f5: compile
Ctrl+B: Launch Breakpoint editor
Ctrl+Tab: Toggle sco/orc files
Ctrl+Shift+A: Add to repository
Ctrl+Shift+X: Insert to repository
-added 'insert soundfile' action to undo list
-fixed WinME problem, thanks to Art Hunkins for his help on this one. Lettuce should now run on all version of Windows, barre 3.1 of course!
-added check to prevent users from closing Lettuce while Csound is playing and thus prevent an unwanted crash
-added a command-line flags edit box for running sco/orc files
-fixed openfile dialogue "Error 474"
-fixed bug to prevent Lettuce from crashing when trying to open envelopes that were not generated in Lettuce
-add inserted code from breakpoint editor to undo list...
-added a Sound Editor button which will launch a sound editor of ones choice
-checkbox option to autoload any soundfiles associated with the current csd/orc/sco in the editor, (this work fine for me with Soundforge but is untested with other editors)
-checkbox added to auto launch any file rendered to disk in the sound editor, this assumes that you are working with the default .csoundrc settings. Again I've only tested this with Soundforge.
-added a soundplayer button for quick playback of sounds in csd/orc/sco, I recommend Mediaplayer Classic http://sourceforge.net/projects/guliverkli/
It's small, loads tons of files types, opens quickly and can be set to 'stay on top'
-added a right-click pop-up command to play soundfiles, make sure the cursor is actually on the soundfile string!
-added warning pop-up about creating standalones from orc/sco files

changes made for version 1.3.1:

- fixed bug where notice was appearing each time the user opens Lettuce...

changes made for version 1.3:

- Users can choose their own colours for symbols such as "/+=%^&*().....
- Support for orc/sco files:
- Users can now run sco/orc files with the play button
- Users can toggle between .orc and .sco file (Ctrl+Tab or Toggle button), so long as they share the same base name, i.e., test.orc, test.sco. The toggle button appears on the right of the performance timer....
- Added an 'AutoSave before performance' checkbox in user settings
- Added an 'AutoSave before switching between score and orchestra file' in user settings

changes made for version 1.2:

- Users can select their own colours for everything from text to message window....
- Sorted the annoying save before close issue, an asterisk will appear if you change anything and trying to close with an asterisk in the title will prompt a save command....
- Compiler should run fine now, I had somehow made a rather foolish assumption that peoples csd files would be less than 2000 characters! This was causing the decode failed message to appear.
- Lettuce now autoloads the last saved file
- Users can now select their own prompt window, this also works with bat files for those of you who prefer MSYS to dos...
- Fixed bug in import orc/sco, thanks to Chris Share for letting me know about that...