From ca0a8f4d6cc24707bc07c3013bff321e2f0c24fd Mon Sep 17 00:00:00 2001 From: Stefano Karapetsas Date: Fri, 13 Jan 2012 23:18:04 +0100 Subject: initial import from Mate-Extra repo --- docs/reference/caja-python-class-reference.xml | 14 + docs/reference/caja-python-column-provider.xml | 105 +++++ docs/reference/caja-python-column.xml | 159 ++++++++ docs/reference/caja-python-enum-reference.xml | 10 + docs/reference/caja-python-file-info.xml | 420 ++++++++++++++++++++ docs/reference/caja-python-info-provider.xml | 247 ++++++++++++ .../caja-python-location-widget-provider.xml | 99 +++++ docs/reference/caja-python-menu-item.xml | 275 +++++++++++++ docs/reference/caja-python-menu-provider.xml | 431 +++++++++++++++++++++ docs/reference/caja-python-menu.xml | 123 ++++++ docs/reference/caja-python-operation-result.xml | 56 +++ docs/reference/caja-python-overview-example.xml | 59 +++ docs/reference/caja-python-overview-methods.xml | 20 + docs/reference/caja-python-overview.xml | 38 ++ .../caja-python-property-page-provider.xml | 124 ++++++ docs/reference/caja-python-property-page.xml | 135 +++++++ docs/reference/caja-python-provider-reference.xml | 14 + docs/reference/caja-python-ref.xml | 35 ++ docs/reference/entities.docbook.in | 1 + 19 files changed, 2365 insertions(+) create mode 100644 docs/reference/caja-python-class-reference.xml create mode 100644 docs/reference/caja-python-column-provider.xml create mode 100644 docs/reference/caja-python-column.xml create mode 100644 docs/reference/caja-python-enum-reference.xml create mode 100644 docs/reference/caja-python-file-info.xml create mode 100644 docs/reference/caja-python-info-provider.xml create mode 100644 docs/reference/caja-python-location-widget-provider.xml create mode 100644 docs/reference/caja-python-menu-item.xml create mode 100644 docs/reference/caja-python-menu-provider.xml create mode 100644 docs/reference/caja-python-menu.xml create mode 100644 docs/reference/caja-python-operation-result.xml create mode 100644 docs/reference/caja-python-overview-example.xml create mode 100644 docs/reference/caja-python-overview-methods.xml create mode 100644 docs/reference/caja-python-overview.xml create mode 100644 docs/reference/caja-python-property-page-provider.xml create mode 100644 docs/reference/caja-python-property-page.xml create mode 100644 docs/reference/caja-python-provider-reference.xml create mode 100644 docs/reference/caja-python-ref.xml create mode 100644 docs/reference/entities.docbook.in (limited to 'docs/reference') diff --git a/docs/reference/caja-python-class-reference.xml b/docs/reference/caja-python-class-reference.xml new file mode 100644 index 0000000..5386ee9 --- /dev/null +++ b/docs/reference/caja-python-class-reference.xml @@ -0,0 +1,14 @@ + + + + + Available Classes + + + + + + + diff --git a/docs/reference/caja-python-column-provider.xml b/docs/reference/caja-python-column-provider.xml new file mode 100644 index 0000000..e9acb19 --- /dev/null +++ b/docs/reference/caja-python-column-provider.xml @@ -0,0 +1,105 @@ + + + + + + caja.ColumnProvider + caja.ColumnProvider Reference + + + + + + + + Synopsis + + + caja.ColumnProvider + + + get_columns + + + + + + + + + + + Description + + + If subclassed, Caja will request a list of caja.Column + objects, which are then displayed when the user is in List mode. + + An extension sub-classing caja.ColumnProvider + will almost always want to sub-class caja.InfoProvider + as well, since that is how an extension provides information for each item in a directory listing. + + + + + caja.ColumnProvider Example + +import os +import urllib + +import caja + +class ColumnExtension(caja.ColumnProvider, caja.InfoProvider): + def __init__(self): + pass + + def get_columns(self): + return caja.Column("CajaPython::block_size_column", + "block_size", + "Block size", + "Get the block size"), + + def update_file_info(self, file): + if file.get_uri_scheme() != 'file': + return + + filename = urllib.unquote(file.get_uri()[7:]) + + file.add_string_attribute('block_size', str(os.stat(filename).st_blksize)) + + + + + + + + + + + Passive Methods + + + caja.ColumnProvider.get_columns + + + get_columns + + + + + + Returns : + a list of caja.Column + + + + + The get_columns() method returns a list of + caja.Column. + + + + + + diff --git a/docs/reference/caja-python-column.xml b/docs/reference/caja-python-column.xml new file mode 100644 index 0000000..0d79032 --- /dev/null +++ b/docs/reference/caja-python-column.xml @@ -0,0 +1,159 @@ + + + + + + caja.Column + caja.Column Reference + + + + + + + + Synopsis + + + caja.Column + gobject.GObject + + + caja.Column + name + attribute + label + description + + + + + + + + + + Ancestry + ++-- gobject.GObject + +-- caja.Column + + + + + + + + + + Description + + + A list of caja.Column objects is returned by caja.ColumnProvider extensions. + + + + + + + + + + + Properties + +
+ + + + + + + + + "attribute" + The attribute name to display. Default value: None + Read-Write + + + + "attribute-q" + The attribute name to display, in quark form. Default value: 0 + Read + + + + "description" + The user-visible description of the column. Default value: None + Read-Write + + + + "label" + The label to display in the column. Default value: None + Read-Write + + + + "name" + The name of the column. Default value: None + Read-Write-ConstructOnly + + + + "xalign" + The x-alignment of the column. Allowed values: [0,1]. Default value: 0 + Read-Write + + + + + +
+ + + + + + + + + Constructor + + + caja.Column + name + attribute + label + description + + + + + name : + identifier of the column + + + attribute : + the file attribute to be displayed in the column + + + label : + the user-visible label for the column + + + description : + a user-visible description of the column + + + + + Creates a new caja.Column object. + + + + + + + diff --git a/docs/reference/caja-python-enum-reference.xml b/docs/reference/caja-python-enum-reference.xml new file mode 100644 index 0000000..ec8216b --- /dev/null +++ b/docs/reference/caja-python-enum-reference.xml @@ -0,0 +1,10 @@ + + + + + Available Enums + + + diff --git a/docs/reference/caja-python-file-info.xml b/docs/reference/caja-python-file-info.xml new file mode 100644 index 0000000..a581c84 --- /dev/null +++ b/docs/reference/caja-python-file-info.xml @@ -0,0 +1,420 @@ + + + + + + caja.FileInfo + caja.FileInfo Reference + + + + + + + + Synopsis + + + caja.FileInfo + gobject.GInterface + + + is_gone + + + + + get_file_type + + + + + get_location + + + + + get_name + + + + + get_uri + + + + + get_activation_uri + + + + + get_parent_info + + + + + get_parent_location + + + + + get_parent_uri + + + + + get_mount + + + + + get_uri_scheme + + + + + get_mime_type + + + + + is_mime_type + mime_type + + + + is_directory + + + + + can_write + + + + + add_emblem + emblem_name + + + + get_string_attribute + attribute_name + + + + add_string_attribute + attribute_name + value + + + + invalidate_extension_info + + + + + + + + + + + + Ancestry + ++-- gobject.GInterface + +-- caja.FileInfo + + + + + + + + + + Description + + + caja.FileInfo objects are passed + to extensions by the caja.InfoProvider. + + + + + + + + + + + Public Methods + + + caja.FileInfo.is_gone + + is_gone + + + + Returns : + whether the file still exists + + + + + + caja.FileInfo.get_file_type + + get_file_type + + + + Returns : + the gio.FileType associated with the file + + + + + + caja.FileInfo.get_location + + get_location + + + + Returns : + the gio.File associated with the file + + + + + + caja.FileInfo.get_name + + get_name + + + + Returns : + the basename of the file + + + + + + caja.FileInfo.get_uri + + get_uri + + + + Returns : + the uri of the file + + + + + + caja.FileInfo.get_activation_uri + + get_activation_uri + + + + Returns : + the activation uri of the file + + + + + + caja.FileInfo.get_parent_info + + get_parent_info + + + + Returns : + the caja.FileInfo object associated with the file's parent + + + + + + caja.FileInfo.get_parent_location + + get_parent_location + + + + Returns : + the gio.File associated with the file's parent location + + + + + + caja.FileInfo.get_parent_uri + + get_parent_uri + + + + Returns : + the uri of the file's parent + + + + + + caja.FileInfo.get_mount + + get_mount + + + + Returns : + the gio.GMount associated with the file, if it exists + + + + + + caja.FileInfo.get_uri_scheme + + get_uri_scheme + + + + Returns : + the uri scheme of the file + + + + + + caja.FileInfo.get_mime_type + + get_mime_type + + + + Returns : + the mimetype of the file + + + + + + caja.FileInfo.is_mime_type + + is_mime_type + mimetype + + + + mimetype : + a mimetype string (i.e. "text/plain") + + + Returns : + whether the file's mimetype string matches the provided mimetype string + + + + + + caja.FileInfo.is_directory + + is_directory + + + + Returns : + whether the item is a directory + + + + + + caja.FileInfo.can_write + + can_write + + + + Returns : + whether the file is writeable + + + + + + caja.FileInfo.add_emblem + + add_emblem + emblem_name + + + + emblem_name : + the name of an emblem to add + + + + + + caja.FileInfo.get_string_attribute + + get_string_attribute + attribute_name + + + + attribute_name : + a string attribute name + + + Returns : + the value associated with the file attribute + + + + + + caja.FileInfo.add_string_attribute + + add_string_attribute + attribute_name + value + + + + attribute_name : + a string attribute name + + + value : + an attribute value + + + + + + caja.FileInfo.invalidate_extension_info + + invalidate_extension_info + + Invalidates the information Caja has about this file, which causes it to request new information + from its caja.InfoProvider providers. + + + + + + + diff --git a/docs/reference/caja-python-info-provider.xml b/docs/reference/caja-python-info-provider.xml new file mode 100644 index 0000000..556bb59 --- /dev/null +++ b/docs/reference/caja-python-info-provider.xml @@ -0,0 +1,247 @@ + + + + + + caja.InfoProvider + caja.InfoProvider Reference + + + + + + + + Synopsis + + + caja.InfoProvider + + + update_file_info + file + + + + update_file_info_full + provider + handle + closure + file + + + + cancel_update + provider + handle + + + + update_complete_invoke + provider + handle + closure + resultcaja.OPERATION_COMPLETE + + + + + + + + + + Description + + + If subclassed, Caja will call update_file_info(_full) to notify extensions of which + files are being viewed by the user. This gives extensions an opportunity to invoke actions on the files, + or to add emblems or attributes. + + + + caja.InfoProvider Example + +import os.path +import caja + +class SimpleInfoProviderExample(caja.InfoProvider): + def __init__(self): + pass + + def update_file_info(self, file): + if os.path.splitext(file.get_name())[1] == ".mp3": + file.add_emblem("multimedia") + + + + + + + + + + + Passive Methods + + + caja.InfoProvider.update_file_info + + + update_file_info + file + + + + + file : + a caja.FileInfo object + + + + + This method is called by Caja for each file or folder that exists under the + current directory listing. There is no return value. + + + + + + caja.InfoProvider.update_file_info_full + + + update_file_info_full + provider + handle + closure + file + + + + + provider : + the current caja.InfoProvider instance + + + handle : + a gobject.gpointer generated solely to track this call + + + closure : + a C Closure that must be passed to update_complete_invoke if that method is called + + + file : + a caja.FileInfo object + + + Returns : + None or a caja.OperationResult enum + + + + + This method is called by Caja for each file or folder that exists under the + current directory listing. Originally, caja.InfoProvider + only provided the update_file_info + method, which blocked Caja when the method required a lot of computation time. This method was + created to allow an extension to tell Caja that it will be spending time on an operation and that + Caja should not block itself during that time. + + + In order to notify Caja of your extension's intentions, you must return a + caja.OperationResult enum. + Then, when the operation has completed, call the self.update_complete_invoke method, passing the provider, + handle and closure variables as parameters. + + + This method was created for backwards compatibility reasons. If your + extension used the update_file_info method and you want non-blocking + usage, you should switch to this method. + + + This method was introduced in caja-python 0.7.0. + + + + + + caja.InfoProvider.cancel_update + + + cancel_update + provider + handle + + + + + provider : + the current caja.InfoProvider instance + + + handle : + a gobject.gpointer generated by a specific update_file_info_full call + + + + + This method is called by Caja when an update_file_info_full call is in progress + but is no longer required. This may happen because the user is moving directories or a file + has been deleted, etc. You may use the handle parameter here to match the + handle parameter passed in update_file_info_full. + + + This method was introduced in caja-python 0.7.0. + + + + + + Active Methods + + + caja.InfoProvider.update_complete_invoke + + + update_complete_invoke + provider + handle + closure + resultcaja.OPERATION_COMEPLETE + + + + + provider : + the current caja.InfoProvider instance + + + handle : + a gobject.gpointer generated by a specific update_file_info_full call + + + closure : + a C Closure that must be passed to update_complete_invoke if that method is called + + + result : + an optional parameter. If left out, caja.OPERATION_COMPLETE is assumed. + Otherwise, you may pass any any of the caja.OperationResult enums. + + + + + An extension must call this method for each update_file_info_full method that + returns the caja.OPERATION_IN_PROGRESS enum. + The method must be called with the provider, handle, and closure parameters which were passed to the earlier update_file_info_full method. + + + This method was introduced in caja-python 0.7.0. + + + + + + diff --git a/docs/reference/caja-python-location-widget-provider.xml b/docs/reference/caja-python-location-widget-provider.xml new file mode 100644 index 0000000..ff39657 --- /dev/null +++ b/docs/reference/caja-python-location-widget-provider.xml @@ -0,0 +1,99 @@ + + + + + + caja.LocationWidgetProvider + caja.LocationWidgetProvider Reference + + + + + + + + Synopsis + + + caja.LocationWidgetProvider + + + get_widget + uri + window + + + + + + + + + + Description + + + If subclassed, Caja will request a widget to be displayed at the top of the directory listing. + + + + caja.LocationWidgetProvider Example + +import caja +import gtk + +class LocationProviderExample(caja.LocationWidgetProvider): + def __init__(self): + pass + + def get_widget(self, uri, window): + entry = gtk.Entry() + entry.set_text(uri) + entry.show() + return entry + + + + + + + + + + + Passive Methods + + + caja.LocationWidgetProvider.get_widget + + + get_widget + uri + window + + + + + uri : + the current folder uri + + + window : + the current gtk.Window instance + + + Returns : + a gtk.Widget object + + + + + This function is called by Caja when it wants a location widget from the extension. + It is called in the main thread before a directory listing is shown, so it should return quickly. + + + + + + diff --git a/docs/reference/caja-python-menu-item.xml b/docs/reference/caja-python-menu-item.xml new file mode 100644 index 0000000..798afa7 --- /dev/null +++ b/docs/reference/caja-python-menu-item.xml @@ -0,0 +1,275 @@ + + + + + + caja.MenuItem + caja.MenuItem Reference + + + + + + + + Synopsis + + + caja.MenuItem + gobject.GObject + + + caja.MenuItem + name + label + tooltip + icon + + + + activate + + + + set_submenu + menu + + + + + + + + + + + Ancestry + ++-- gobject.GObject + +-- caja.MenuItem + + + + + + + + + + Description + + + caja.MenuItem objects are appended to lists to create menus and submenus. + + + + + + + + + + + Properties + +
+ + + + + + + + + "icon" + Name of the icon to display in the menu item. Default value: None + Read-Write + + + + "label" + The label to display to the user. Default value: None + Read-Write + + + + "menu" + The caja.Menu menu object belonging to this item. May be None. + Read-Write + + + + "name" + The name of the item. Default value: None + Read-Write-ConstructOnly + + + + "priority" + Whether or not to show priority text in toolbars. Default value: True + Read-Write + + + + "sensitive" + Whether or not the menu item is sensitive. Default value: True + Read-Write + + + + "tip" + The tooltip for the menu item. Default value: None + Read-Write + + + + + +
+ + + + + + + + + Signals + + + "activate" + + callback + item + user_param1 + ... + + + + + + + + + + + + + + + Constructor + + + caja.MenuItem + name + label + tooltip + icon + + + + + name : + identifier of the item + + + label : + the user-visible label for the item + + + tooltip : + the user-visible tooltip for the item + + + icon : + Name of the icon to display in the item + + + + + Creates a new caja.MenuItem object. + + + + + + + + + + Public Methods + + + caja.MenuItem.activate + + activate + + + + Generates the "activate" signal for this caja.MenuItem. + + + + + caja.MenuItem.set_submenu + + set_submenu + menu + + + + menu : + a caja.Menu + + + + Attaches a caja.Menu as the submenu for this caja.MenuItem. + + + + + + + + + + + Signal Details + + + The "activate" caja.MenuItem Signal + + + callback + item + user_param1 + ... + + + + + item : + the caja.MenuItem being activated + + + user_param1 : + User-defined parameter the user attaches to the signal connector + + + ... : + Additional parameter(s) the user attaches to the signal connector + + + + + Emits the "activate" signal. + + + + + + + + + diff --git a/docs/reference/caja-python-menu-provider.xml b/docs/reference/caja-python-menu-provider.xml new file mode 100644 index 0000000..0050bec --- /dev/null +++ b/docs/reference/caja-python-menu-provider.xml @@ -0,0 +1,431 @@ + + + + + + caja.MenuProvider + caja.MenuProvider Reference + + + + + + + + Synopsis + + + caja.MenuProvider + + + get_file_items + window + files + + + + get_file_items_full + provider + window + files + + + + get_background_items + window + folder + + + + get_background_items_full + provider + window + folder + + + + get_toolbar_items + window + folder + + + + get_toolbar_items_full + provider + window + folder + + + + emit_items_updated_signal + provider + + + + + + + + + + Description + + + If subclassed, Caja will request a list of caja.MenuItem objects, + which are then attached to various menus. Caja expects at least one of + the following methods to be defined (or their *_full variants): get_file_items, + get_background_items, or get_toolbar_items. + + + + caja.MenuProvider Example + +import os +import urllib + +import gtk +import caja +import mateconf + +TERMINAL_KEY = '/desktop/mate/applications/terminal/exec' + +class OpenTerminalExtension(caja.MenuProvider): + def __init__(self): + self.client = mateconf.client_get_default() + + def _open_terminal(self, file): + filename = urllib.unquote(file.get_uri()[7:]) + terminal = self.client.get_string(TERMINAL_KEY) + + os.chdir(filename) + os.system('%s &' % terminal) + + def menu_activate_cb(self, menu, file): + self._open_terminal(file) + + def menu_background_activate_cb(self, menu, file): + self._open_terminal(file) + + def get_file_items(self, window, files): + if len(files) != 1: + return + + file = files[0] + if not file.is_directory() or file.get_uri_scheme() != 'file': + return + + item = caja.MenuItem('CajaPython::openterminal_file_item', + 'Open Terminal' , + 'Open Terminal In %s' % file.get_name()) + item.connect('activate', self.menu_activate_cb, file) + return item, + + def get_background_items(self, window, file): + item = caja.MenuItem('CajaPython::openterminal_item', + 'Open Terminal Here', + 'Open Terminal In This Directory') + item.connect('activate', self.menu_background_activate_cb, file) + return item, + + + + + + + + + + Signals + + + "items-updated" + + callback + + + + + + + + + + + + + + + Passive Methods + + + caja.MenuProvider.get_file_items + + + get_file_items + window + files + + + + + window : + the current gtk.Window instance + + + menu : + a list of caja.FileInfo objects. + + + Returns : + a list of caja.MenuItem objects + + + + + The get_file_items() method returns a list of + caja.MenuItem objects. + + + + + caja.MenuProvider.get_file_items_full + + + get_file_items_full + provider + window + files + + + + + provider : + the current caja.MenuProvider instance + + + window : + the current gtk.Window instance + + + files : + a list of caja.FileInfo objects. + + + Returns : + a list of caja.MenuItem objects + + + + + The get_file_items_full() method returns a list of + caja.MenuItem objects. + + + This method was created in order to allow extension writers to call the + caja.MenuProvider.emit_items_updated_signal, which must + be passed the current provider instance. + + + This method was introduced in caja-python 0.7.0. + + + + + + caja.MenuProvider.get_background_items + + + get_background_items + window + folder + + + + + window : + the current gtk.Window instance + + + folder : + the current folder, as a caja.FileInfo object. + + + Returns : + a list of caja.MenuItem objects + + + + + The get_background_items() method returns a list of + caja.MenuItem objects. + + + + + caja.MenuProvider.get_background_items_full + + + get_background_items_full + provider + window + folder + + + + + provider : + the current caja.MenuProvider instance + + + window : + the current gtk.Window instance + + + folder : + the current folder, as a caja.FileInfo object. + + + Returns : + a list of caja.MenuItem objects + + + + + The get_background_items_full() method returns a list of + caja.MenuItem objects. + + + This method was created in order to allow extension writers to call the + caja.MenuProvider.emit_items_updated_signal, which must + be passed the current provider instance. + + + This method was introduced in caja-python 0.7.0. + + + + + + caja.MenuProvider.get_toolbar_items + + + get_toolbar_items + window + folder + + + + + window : + the current gtk.Window instance + + + folder : + the current folder, as a caja.FileInfo object. + + + Returns : + a list of caja.MenuItem objects + + + + + The get_toolbar_items() method returns a list of + caja.MenuItem objects. + + + + + caja.MenuProvider.get_toolbar_items_full + + + get_toolbar_items_full + provider + window + folder + + + + + provider : + the current caja.MenuProvider instance + + + window : + the current gtk.Window instance + + + folder : + the current folder, as a caja.FileInfo object. + + + Returns : + a list of caja.MenuItem objects + + + + + The get_toolbar_items_full() method returns a list of + caja.MenuItem objects. + + + This method was created in order to allow extension writers to call the + caja.MenuProvider.emit_items_updated_signal, which must + be passed the current provider instance. + + + This method was introduced in caja-python 0.7.0. + + + + + + Active Methods + + + caja.MenuProvider.emit_items_updated_signal + + + emit_items_updated_signal + provider + + + + + provider : + the current caja.MenuProvider instance + + + + + Emits the "items-updated" signal. + + + This method was introduced in caja-python 0.7.0. + + + + + + + + + + + + Signal Details + + + The "items-updated" caja.MenuProvider Signal + + + Emits the "items-updated" signal. + + + + + + + + diff --git a/docs/reference/caja-python-menu.xml b/docs/reference/caja-python-menu.xml new file mode 100644 index 0000000..678585b --- /dev/null +++ b/docs/reference/caja-python-menu.xml @@ -0,0 +1,123 @@ + + + + + + caja.Menu + caja.Menu Reference + + + + + + + + Synopsis + + + caja.Menu + gobject.GObject + + + caja.Menu + + + + append_item + item + + + + get_items + + + + + + + + + + + Ancestry + ++-- gobject.GObject + +-- caja.Menu + + + + + + + + + + Description + + + A caja.Menu object allows an extension to create sub-menus. + + + + + + + + + + + + Constructor + + + caja.Menu + + + + Creates a new caja.Menu object. + + + + + + + + + + + Public Methods + + + caja.Menu.append_item + + append_item + item + + + + item : + a caja.MenuItem + + + + + Append a caja.MenuItem to a caja.Menu. + + + + + caja.Menu.get_items + + get_items + + + Returns a list of caja.MenuItem objects attached to the caja.Menu. + + + + + + + + diff --git a/docs/reference/caja-python-operation-result.xml b/docs/reference/caja-python-operation-result.xml new file mode 100644 index 0000000..3720f2f --- /dev/null +++ b/docs/reference/caja-python-operation-result.xml @@ -0,0 +1,56 @@ + + + + + + caja.OperationResult + caja.OperationResult Reference + + + + + + + + + + Description + + + The caja.OperationResult constants are + used by the caja.InfoProvider provider to + notify Caja what the extension intends to do when Caja calls the extension's update_file_info_full + method. The possible values are as follows: + + + + + + caja.OPERATION_COMPLETE + + The operation is complete and Caja can move on to the next update_file_info_full call. + + + + caja.OPERATION_IN_PROGRESS + + The operation is in progress and running asynchronously and Caja should wait until the update_complete_invoke method + is called before moving on to the next update_file_info_full call. + + + + caja.OPERATION_FAILED + + The operation has failed. + + + + + + + + + + + diff --git a/docs/reference/caja-python-overview-example.xml b/docs/reference/caja-python-overview-example.xml new file mode 100644 index 0000000..b429365 --- /dev/null +++ b/docs/reference/caja-python-overview-example.xml @@ -0,0 +1,59 @@ + + + + + A Simple Extension + + Create an empty file with the following code: + + + A Simple Extension + +import caja + +class SimpleMenuExtension(caja.MenuProvider): +def __init__(self): + pass + +def menu_activate_cb(self, menu, file): + print "menu_activate_cb",file + +def get_file_items(self, window, files): + if len(files) != 1: + return + + file = files[0] + + item = caja.MenuItem( + "SimpleMenuExtension::Show_File_Name", + "Showing %s" % file.get_name(), + "Showing %s" % file.get_name() + ) + item.connect('activate', self.menu_activate_cb, file) + + return [item] + + + Save this file as TestExtension.py in the ~/.caja/python-extensions folder. + You may need to create this folder. To run, open the terminal and type: + + + +$ caja -q +$ caja --no-desktop + + + Once Caja starts, right-click on a file and you should see a new menu item, + "Showing #filename#". It is as simple as that! + + As mentioned above, in order to + get loaded by Caja, a python extension must import the caja module, + create a class derived from a caja *Provider, then create the methods that + will be called by Caja when it requests information from its providers. + In this case, when someone right-clicks on a file, Caja will ask all of its + MenuProviders for additional menu items to show the user. When folders or files are clicked, + the get_file_items method is called and a list of caja.MenuItems is expected. + + diff --git a/docs/reference/caja-python-overview-methods.xml b/docs/reference/caja-python-overview-methods.xml new file mode 100644 index 0000000..973aecd --- /dev/null +++ b/docs/reference/caja-python-overview-methods.xml @@ -0,0 +1,20 @@ + + + + + + Explanation of Passive/Active Methods + + Because caja-python is an interface to a Caja' extension interface rather than a true library, it is + rather quirky in how it works. One example of this is that several providers have additional public methods + that an extension actively calls, rather than the extension defining and the method in their class that is called by + Caja. You can see this with the caja.MenuProvider.emit_items_updated_signal + and caja.InfoProvider.update_complete_invoke methods, which + the extension actively calls, passing the provider instance as a parameter. + + + Due to this confusion, I have termed these actively-called methods Active Methods and the methods + called by Caja are termed Passive Methods. + diff --git a/docs/reference/caja-python-overview.xml b/docs/reference/caja-python-overview.xml new file mode 100644 index 0000000..e92dedf --- /dev/null +++ b/docs/reference/caja-python-overview.xml @@ -0,0 +1,38 @@ + + + + + Overview + + Writing a Caja-Python extension is a fairly straight-forward process. + One simply imports the caja module and creates a class which is derived from a number + of the caja module's classes. When an extension derives a class, it becomes a "provider", + telling Caja to ask it for information. There are several types of providers + available for extensions to use: there is MenuProvider, LocationWidgetProvider, + ColumnProvider, PropertyPageProvider, and InfoProvider, all of which will be explained + in more detail below. Your class can be derived from multiple providers. + + Here are the basic steps: + + 1. A script is written and installed to the standard python extensions install path + 2. Caja is (re)started and loads the Caja-Python C extension, which in turn loads all python extensions + 3. Any python script in the standard python extensions install path that imports the caja module and derives + the main class from a caja module class will be loaded + + +A note about the standard python extensions install path + +The install path for individual users is ~/.caja/python-extensions. +The system-wide install path is $PREFIX/lib/caja/extensions-2.0/python. However, some 64 bit distributions, +such as Fedora, put Caja-Python extensions in $PREFIX/lib64/caja/extensions-2.0/python. +As of caja-python 0.7.0, caja-python looks in ~/.local/share/caja-python/extensions +for local extensions and $PREFIX/share/caja-python/extensions for global extensions. + + + + + + + diff --git a/docs/reference/caja-python-property-page-provider.xml b/docs/reference/caja-python-property-page-provider.xml new file mode 100644 index 0000000..1ecb50f --- /dev/null +++ b/docs/reference/caja-python-property-page-provider.xml @@ -0,0 +1,124 @@ + + + + + + caja.PropertyPageProvider + caja.PropertyPageProvider Reference + + + + + + + + Synopsis + + + caja.PropertyPageProvider + + + get_pages + files + + + + + + + + + + Description + + + If subclassed, Caja will request a list of custom property pages that should + appear when a user opens the Properties dialog for a file or folder. + + + + caja.PropertyPageProvider Example + +import hashlib +import urllib + +import gtk +import caja + +class MD5SumPropertyPage(caja.PropertyPageProvider): + def __init__(self): + pass + + def get_property_pages(self, files): + if len(files) != 1: + return + + file = files[0] + if file.get_uri_scheme() != 'file': + return + + if file.is_directory(): + return + + filename = urllib.unquote(file.get_uri()[7:]) + + self.property_label = gtk.Label('MD5Sum') + self.property_label.show() + + self.hbox = gtk.HBox(0, False) + self.hbox.show() + + label = gtk.Label('MD5Sum:') + label.show() + self.hbox.pack_start(label) + + self.value_label = gtk.Label() + self.hbox.pack_start(self.value_label) + + md5sum = hashlib.md5(filename).hexdigest() + self.value_label.set_text(md5sum) + self.value_label.show() + + return caja.PropertyPage("CajaPython::md5_sum", + self.property_label, self.hbox), + + + + + + + + + + + Passive Methods + + + caja.PropertyPageProvider.get_pages + + + get_pages + + + + + + files : + a list of caja.FileInfo objects. + + + Returns : + a list of caja.PropertyPage objects + + + + + This function is called by Caja when it wants property page items from the extension. + It is called in the main thread before a property page is shown, so it should return quickly. + + + + + + diff --git a/docs/reference/caja-python-property-page.xml b/docs/reference/caja-python-property-page.xml new file mode 100644 index 0000000..c1131ff --- /dev/null +++ b/docs/reference/caja-python-property-page.xml @@ -0,0 +1,135 @@ + + + + + + caja.PropertyPage + caja.PropertyPage Reference + + + + + + + + Synopsis + + + caja.PropertyPage + gobject.GObject + + + caja.PropertyPage + name + label + page + + + + + + + + + + Ancestry + ++-- gobject.GObject + +-- caja.PropertyPage + + + + + + + + + + Description + + + A caja.PropertyPage object is returned by caja.PropertyPageProvider extensions. + + + + + + + + + + + Properties + +
+ + + + + + + + + "label" + The label widget displayed in the notebook tab. + Read-Write + + + + "name" + The name of the page. Default value: None + Read-Write-ConstructOnly + + + + "page" + The property page widget + Read-Write + + + + + +
+ + + + + + + + + Constructor + + + caja.PropertyPage + name + label + page + + + + + name : + identifier of the property page + + + label : + the user-visible label for the property page + + + page : + the property page widget + + + + + Creates a new caja.PropertyPage object. + + + + + + + diff --git a/docs/reference/caja-python-provider-reference.xml b/docs/reference/caja-python-provider-reference.xml new file mode 100644 index 0000000..898c6c8 --- /dev/null +++ b/docs/reference/caja-python-provider-reference.xml @@ -0,0 +1,14 @@ + + + + + Provider Interfaces + + + + + + + diff --git a/docs/reference/caja-python-ref.xml b/docs/reference/caja-python-ref.xml new file mode 100644 index 0000000..e54ad6c --- /dev/null +++ b/docs/reference/caja-python-ref.xml @@ -0,0 +1,35 @@ + + +%entities; + + +]> + + + &builddate; + caja-python Reference Manual + Reference Manual for caja-python &version; + For caja-python version &version; + + + Adam + Plumb + + + + This reference describes the classes of the caja-python module. + + + + + + + + + + + + + diff --git a/docs/reference/entities.docbook.in b/docs/reference/entities.docbook.in new file mode 100644 index 0000000..7b2eb41 --- /dev/null +++ b/docs/reference/entities.docbook.in @@ -0,0 +1 @@ + -- cgit v1.2.1