rox.saving | index

`All ROX applications that can save documents should use drag-and-drop saving.
The document itself should use the Saveable mix-in class and override some of the
methods to actually do the save.
If you want to save a selection then you can create a new object specially for
the purpose and pass that to the SaveBox.`

Classes

``

gtk.Dialog(gtk.Window)
  SaveBox
    StringSaver(SaveBox, Saveable)
Saveable
  SaveFilter
rox.UserAbort(exceptions.Exception)
  AbortSave
gtk.VBox(gtk.Box)
  SaveArea

class AbortSave(rox.UserAbort)
`` | `Raise this to cancel a save. If a message is given, it is displayed in a normal alert box (not in the report_exception style). If the message is None, no message is shown (you should have already shown it!)`

Methods defined here:

__init__(self, message)

show(self)

class SaveArea(gtk.VBox)
`` | `A SaveArea contains the widgets used in a save box. You can use this to put a savebox area in a larger window.`

Methods defined here:

__init__(self, document, uri, type)
  `'document' must be a subclass of Saveable.
  'uri' is the file's current location, or a simple name (eg 'TextFile')
  if it has never been saved.
  'type' is the MIME-type to use (eg 'text/plain').`

confirm_new_path(self, path)
  `User wants to save to this path. If it's different to the original path,
  check that it doesn't exist and ask for confirmation if it does.
  If document.save_last_stat is set, compare with os.stat for an existing file
  and warn about changes.
  Returns true to go ahead with the save.`

drag_begin(self, drag_box, context)

drag_data_get(self, widget, context, selection_data, info, time)

drag_end(self, widget, context)

save_done(self)

save_to_file_in_entry(self)
  `Call this when the user clicks on an OK button you provide.`

set_type(self, type, icon=None)
  `Change the icon and drag target to 'type'.
  If 'icon' is given (as a GtkImage) then that icon is used,
  otherwise an appropriate icon for the type is used.`

set_uri(self, uri)
  `Data is safely saved somewhere. Update the document's URI and save_last_stat (for local saves).
  Internal.`

class SaveBox(gtk.Dialog)
`` | `A SaveBox is a GtkDialog that contains a SaveArea and, optionally, a Discard button. Calls rox.toplevel_(un)ref automatically.`

Methods defined here:

__init__(self, document, uri, type='text/plain', discard=False)
  `See SaveArea.__init__.
  If discard is True then an extra discard button is added to the dialog.`

build_main_area(self)
  `Place self.save_area somewhere in self.vbox. Override this
  for more complicated layouts.`

set_save_in_progress(self, in_progress)
  `Called when saving starts and ends. Shade/unshade any widgets as
  required. Make sure you call the default method too!
  Not called if box is destroyed from a recursive mainloop inside
  a save_to_* function.`

set_type(self, type, icon=None)
  `See SaveArea's method of the same name.`

class SaveFilter(Saveable)

``

`This Saveable runs a process in the background to generate the
save data. Any python streams can be used as the input to and
output from the process.
The output from the subprocess is saved to the output stream (either
directly, for fileno() streams, or via another temporary file).
If the process returns a non-zero exit status or writes to stderr,
the save fails (messages written to stderr are displayed).
`

Methods defined here:

save_cancelled(self)
  `Send SIGTERM to the child processes.`

save_to_stream(self, stream)

set_stdin(self, stream)
  `Use 'stream' as stdin for the process. If stream is not a
  seekable fileno() stream then it is copied to a temporary file
  at this point. If None, the child process will get /dev/null on
  stdin.`

class Saveable
`` | `This class describes the interface that an object must provide to work with the SaveBox/SaveArea widgets. Inherit from it if you want to save. All methods can be overridden, but normally only save_to_stream() needs to be. You can also set save_last_stat to the result of os.stat(filename) when loading a file to make ROX-Lib restore permissions and warn about other programs editing the file.`

Methods defined here:

can_save_to_file(self)
  `Indicates whether we have a working save_to_stream or save_to_file
  method (ie, whether we can save to files). Default method checks that
  one of these two methods has been overridden.`

can_save_to_selection(self)
  `Indicates whether we have a working save_to_stream or save_to_selection
  method (ie, whether we can save to selections). Default methods checks that
  one of these two methods has been overridden.`

discard(self)
  `Discard button clicked, or document safely saved. Only called if a SaveBox
  was created with discard=1.
  The user doesn't want the document any more, even if it's modified and unsaved.
  Delete it.`

save_cancelled(self)
  `If you multitask during a save (using a recursive mainloop) then the
  user may click on the Cancel button. This function gets called if so, and
  should cause the recursive mainloop to return.`

save_done(self)
  `Time to close the savebox. Default method does nothing.`

save_set_permissions(self, path)
  `The default save_to_file() creates files with the mode 0600
  (user read/write only). After saving has finished, it calls this
  method to set the final permissions. The save_set_permissions():
  - sets it to 0666 masked with the umask (if save_mode is None), or
  - sets it to save_last_stat.st_mode (not masked) otherwise.`

save_to_file(self, path)
  `Write data to file. Raise an exception on error.
  The default creates a temporary file, uses save_to_stream() to
  write to it, then renames it over the original. If the temporary file
  can't be created, it writes directly over the original.`

save_to_selection(self, selection_data)
  `Write data to the selection. The default method uses save_to_stream().`

save_to_stream(self, stream)
  `Write the data to save to the stream. When saving to a
  local file, stream will be the actual file, otherwise it is a
  cStringIO object.`

set_uri(self, uri)
  `When the data is safely saved somewhere this is called
  with its new name. Mark your data as unmodified and update
  the filename for next time. Saving to another application
  won't call this method. Default method does nothing.`

class StringSaver(SaveBox, Saveable)
`` | `A very simple SaveBox which saves the string passed to its constructor.`

Methods defined here:

__init__(self, string, name)
  `'string' is the string to save. 'name' is the default filename`

save_to_stream(self, stream)

Functions

``

image_for_type(type)
  `Search <Choices> for a suitable icon. Returns a pixbuf, or None.`