Ubuntu Studio Menu Item Editing utility
=======================================

This is a utility that allows the user to create or edit menu items also
known as "desktop" files.

What it will not do:
====================
	- Create new menu directories.
	- Add items to directories that are not normally a part of
		Ubuntu Studio. (a Wine directory structure for example)
	- Move Items that are "hard coded" in place in the menu structure
	- Create or manipulate Link type desktop files. Our menus seem to
		ignore these anyway.
		These can still be created by dragging a link from a browser onto
		the desktop and editing with a right click. If you want to add a link
		to the menu, use xdg-open. See "Ubuntu Studio Mailing List" for an
		example.
	- Make system wide changes. This utility will only create and edit
		menu items for the current user.

How to use Menu Add
===================
Before Menu Add can do anything it has to have a file name to work with.
That file name can come from one of three places:
	1) items local to this user ( ~/.local/share/applications/ ) These
			can be selected with the "User Items" drop down menu.
	2) items from the system directories. These can be selected from the
			"system Items" drop down menu.
	3) Item to create in the "New Item Filename:" box. The file extension
			is not required and the file name is checked for invalid
			characters. The name should be unique. If you happen to use a name
			that is allready used somewhere else in the system, your version
			will override that version. It is easy to tell if you have picked
			a file name already in use because at the edit stage the boxes will
			already be filled out. Best to cancel the edit and choose another
			filename. The file name does not have to be exectly the same as
			the application it runs but should be similar enough that browsing
			the file folder makes it obvious what the desktop file is for.

Once a file name has been selected Menu Add will check for a desktop
file of that name in all the above places. It will read the file to find
out what some of the settings are and to make sure that the file is in
a usable state.

If the file is not yet usable as in a new item, only the
"Edit Selected Item" button will be available.

Editing the desktop file:
The "Edit Selected File" button opens an Edit Launcher dialog.

The top field is "Name:" this is the name as you wish it to appear in
the menu. It is ok to put spaces, capitalization, etc. in this box. This
Field is Required. It is not possible to create or save an item without
a name.

The second field is "Comment:" Whatever is put in this field will appear
in the menu as a tool tip when the mouse hovers over the menu item.

The third field is "Command:" This is the command that would be typed on
a command line to have the desired effect. Often it is just the filename
of the executable and there is a file browser button beside the field
to allow searching for that file. However in many cases some command line
parameters may be needed to have the application open in the desired
mode or with the desired file. This field is also Required. It is not
possible to create or save an item without a Command.

The fouth field is "Working Directory:" In most cases this will be left
blank or empty and the application will be run from the user's home
directory. If it is desired to start in another directory, this is the
place to set the directory the application should open. Some uses for
this is to open an application in the directory where the files this
application has it's files if the application doesn't already go there
on it's own. An example would be fluid synth which looks for sf2 files
in which ever directory it is run in. Setting it to run in the directory
the user has put their sf2 files in would be ideal.

The fifth field in "Icon:" Clicking on this opens an icon browser to
allow choosing an icon to go with your Item. If you wish to use a custom
icon, it should be placed in ~/.local/share/icons/hicolour/ in the
subdirectory with the size of your icon. The expected format for the
icons is either png or svg. It is often easiest to use an svg of the
largest size in that directory with symbolic links to the smaller sizes
so that one file will work for all. Inside of the size directory there
is an apps directory (or one can be made) inside of which the icon
should be put.

The last field has two options:
	Use startup notification. This sets the mouse in starting mode while
		the application is starting but has not yet opened a window.
	Run in terminal. This is for any application that does not make it's
		own window and requires a terminal to run in. Examples are top, nano
		and alsamixer.

After the desired fields are filled in, the Save button will save the
desktop file... however, by default it will not yet be active, check the
"Active" check box and it should now be visible in the menu.

There are some other functions that can be used after the original 
desktop file has been created.

Menu placement can be set using the two dropdowns for "Menu Folder:" and
"SubMenu Folder:". These dropdowns list the available folders in the
UbuntuStudio menu. Some of these folders have subfolders and those areas
can be chosen as well. If these dropdowns are not used the item will
show in the "Other" category or if it is an existing item being edited,
it will retain the current place in the menu.

Note: There are a number of items in the Ubuntu Studio application
collection that do not automatically go into the folder they should
and so have been "hard coded" to be where they are. Changing the
folder for these items will not move them. As a work around it is
possible to create a new item in the desired folder and then edit the
system item by deselecting the "Visible" check box. In this case it is
a good practice to edit the name of the original to include the text
"original". As this item is not visible the extra text will not show
in the menu. The replacement item should probably use the same filename
with -1 appended for easy tracking.

The menu item can be made visible or not by selecting or deselecting
the "Visible" check box.

The edited item can be made made active or not by selecting or
deselecting the "active" check box. New items all start out inactive and
have to be made active so they work. In the case where a system item has
been overridden with a user item, making inactive will allow the system
item to work as it did originally.

Normally, when editing an item, Menu Add will choose the user version
over the system version even if it is inactive. Selecting the
"Use System Original" check box will use the original system desktop
file as template for editing instead.

The last row contain four buttons:
	About: shows the about dialog.
	Edit Selected Item: See above.
	Help: This page.
	Exit: Exit Menu Add
	
