Documentation for developers - users read README instead!


To use the python libraries, add the findrox.py file (in this directory) to
your application and include it right at the start (from the AppRun). This
will find ROX-Lib and add ROX-Lib/python to sys.path.

You can then include the other files, eg:

	import findrox
	from rox.MultipleChoice import MultipleChoice

The following modules are provided:

	choices		 - Load and save user choices
	filer		 - Open directories with ROX-Filer, etc
	MultipleChoice	 - A message box with buttons along the bottom
	SaveBox/SaveArea - Drag and drop saving
	Toolbar		 - A ROX-Filer style toolbar
	XDSLoader	 - Allow files to be dropped on your widgets
	options		 - Load, save and edit settings
	Menu		 - Menus with key-bindings


choices
~~~~~~~
The Choices system is explained at:
	http://rox.sourceforge.net/choices.php3

When you want to load some settings, use:

	path = choices.load('MyProgram', 'Filename')

If path is not None then load it, else use internal defaults.

To save choices:

	path = choices.save('MyProgram', 'Filename')

If path is not None then save the choices there, else do not save (saving
is disabled at the user's request).

This creates any missing directories - pass 'create = 0' if you don't want
that (eg, to show the user where you will save without actually saving).


filer
~~~~~
You can get ROX-Filer to open a directory using:
	
	from rox import filer
	filer.open_dir('/path/to/dir')

If you want to indicate a particular file (make it flash), use:

	filer.show_file('/path/to/dir/file')

To make the filer notice that a file has changed in some way, use:

	filer.examine('/path/to/dir/file')


MultipleChoice
~~~~~~~~~~~~~~
This is a dialog box with a message and some buttons along the bottom.
You can use it like this:

	box = MultipleChoice('Really quit?', ['OK', 'Cancel'])
	box.set_title('Question:')
	result = box.wait()

Result is 0 if OK was chosen, 1 if Cancel was chosen and -1 if the box was
closed without a choice being made. When used this way, the box is modal
(no other widgets in your program will do anything until the user makes a
choice).

You may also specify callback functions, by using a tuple instead of a string
for a button. If you use use show() instead of wait() then the call returns
immediately and the box isn't modal.

	box = MultipleChoice('Really quit?', [('OK', mainquit), 'Cancel'])
	box.set_title('Question:')
	box.show()

Finally, you can pass extra arguments to the button callback functions, make
a callback function None to make an insensitive button and give a callback
for when the box is cancelled:

	box = MultipleChoice('Really quit?',
				[('OK', mainquit), 
				 ('Help', show_help, 'box_help'),
				 ('Crash', None),
				 'No'],
				box_cancelled)
	box.show()


SaveBox/SaveArea
~~~~~~~~~~~~~~~~
When you want to let the user save some data somewhere, use a SaveBox.
You need to pass the constructor an object which can save, the default
filename, and the MIME type for the data, eg:

	box = SaveBox(my_doc, my_doc.uri, 'text/plain')
	box.show()

'my_doc' should have the following methods:

	set_uri(uri)
		Data is safely saved to this location, mark unmodified.
		May be omitted.

	save_get_data()
		Return a string containing the data to save.

	save_as_file(path)
		Write data to file, return TRUE on success.
		If missing, uses get_save_data() and writes that.

	save_as_selection(selection_data)
		Write data to the selection.
		If missing, uses get_save_data() and sends that.

	discard()
		Only used if discard = TRUE. Called when Discard button
		is clicked, or when data is saved safely.

If save_get_data is NOT provided, then one or both of save_as_file and
save_as_selection must be present. If only one is provided then the other
function is disabled.

If the user tries to close a document window containing modified data then you
may wish to create the savebox with 'discard = 1'. This adds a Discard button
which, if clicked, does:

	my_doc.discard()

Example:

	import findrox
	from rox.SaveBox import SaveBox
	from rox import support
	from gtk import *

	class Doc:
		data = 'Some Text'

		def save_get_data(self):
			return self.data

	doc = Doc()

	box = SaveBox(doc, 'TextFile', 'text/plain')
	box.show()
	
	support.rox_toplevel_unref()
	support.rox_mainloop()

See also the 'ROX-Lib/bin/savebox' example program.

You may also use the save_area.set_type() method to change the MIME type
and icon of the data being saved. This can be used if the application can
save in several formats (perhaps selected from a menu in the savebox). The
optional icon field is a pair (pixmap, mask) to use for the icon. If not given,
or None, the appropriate icon for the type is used.

	savebox.set_type('text/plain', icon = (pixmap, mask))

The SaveArea widget is similar to SaveBox, but can be added to an existing
window. In fact, a SaveBox is just a window with a SaveArea inside it.
The widget is created and used in the same way, except that there is no
'discard' field.


Toolbar
~~~~~~~
To add a toolbar to your application, put a VBox in the main window and
pack_start a Toolbar into it, like this:

	window = GtkWindow()
	vbox = GtkVBox(FALSE, 0)
	window.add(vbox)
	toolbar = Toolbar()
	vbox.add(toolbar)

You can then add tools to the toolbar like this:

	tool = toolbar.add_button('Quit', app_dir + '/icons/quit.xpm',
				  'This tool quits the application')
	
'Quit' is the name of the tool (not currently used, but a large
style will probably be supported at some point).

The second argument is an icon in XPM format to display in the button.
The third argument is the tooltip for the tool.

You can connect to the 'clicked' signal of 'tool' to handle clicks.

The icons are cached, not reloaded every time you create a new toolbar.

XDSLoader
~~~~~~~~~
To make a widget allow drops, add XDSLoader to its classes list and
initialise it with a list of allowed types (None prevents data being
dragged in from other applications, but still allows files):

	from rox.XDSLoader import XDSLoader

	class MyWindow(GtkWindow, XDSLoader):
		def __init__(self, filename = None):
			GtkWindow.__init__(self)
			XDSLoader.__init__(self, ['text/plain'])

When a file is dragged onto the window the method xds_load_uris() gets
called with a list of URIs to load. If you don't override it, the default
is to call xds_load_from_file(path) for each (local) file in the list.

If some data (not a file) is dropped on the window then
xds_load_from_selection(selection) is called.

In either case, the default methods get the data and call
xds_load_data(data).

options
~~~~~~~
Initialise the options system right at the start of your program:

	from rox import options
        options.init('MyEdit')

Register each option before using it. Give the name ('section_option') and
a default value:

	options.register('section_option', 'Default')

Get the current value using:

	options.get('section_option')

Bring up the options box with:

	options.edit()

You'll need to create an Options.xml file with the layout for the box.
See the the Options help file.

Menu
~~~~
This widget makes it easier to create a menu with key bindings that can
be shared between several windows.

Create each menu only once (not once-per-window):
	
	from rox.Menu import Menu
	menu = Menu('MyProg', 'main', [
			('/Save', 'save', '', 'F3'),
			('/Options...', 'show_options', ''),
			('/Close', 'close', ''),
			])

'MyProg' and 'main' are used for loading the short-cuts from Choices.
Each item in the list is a menu item:

	path/label	Can nest too, eg '/File/Save'
	callback	Name of the callback (a string)
	type 		(as for GtkItemFactory's create_items)
	key		Optional short-cut. Only used if no bindings
			are found in Choices.

For each window that can show this menu, do this to accept short-cuts:

	menu.attach(window, object)

The menu will call object.save(), object.show_options(), etc in response to
menu items being chosen.

To open the menu in response to a mouse click:

	menu.popup(object, event)

Saving shortcuts (not currently implemented) is done with:

	menu.save()
