Another try at Desktop::Editor

[Martijn van Beers <martijn earthling net>]

Hi,

another new try.

* clearer comments (I hope)
* Added exception to EditorStream for unsupported options
* added set_stream and changed functions to EditorView so
  EditorViews can be in another process than the Editor (editors
  don't need to support this)
* Added exception to Desktop::Editor so editors can say they don't
  support a certain EditorView type
* Added exception for Editors that don't support multiple views

module Desktop {

	interface EditorStream;
	interface EditorView;
	interface Editor;

	/* This interface is intended as an add-on to GNOME::Stream
	 */
	interface EditorStream : GNOME::Unknown {
		typedef long SearchOption;
		/* whether to ignore case while searching */
		const SearchOption SEARCH_ICASE = 1;
		/* whether to search backwards */
		const SearchOption SEARCH_REVERSE = 2;
		/* whether the search-string is a regexp */
		const SearchOption SEARCH_REGEX = 4;

		exception OptionsNotSupported { long optionmask };
		/**
		 * search:
		 * @regexp: the string or regexp to find
		 * @whence: search from where
		 * @flags: Options modifying the search
		 *
		 * lets you search for a string in the stream.
		 * Returns the position of the beginning of the searchstring
		 * or -1 if the string was not found. The search-string can
		 * optionally be a regular expression (Editors do not have
		 * to support this)
		 */
		 long search (in string                  regexp,
		              in GNOME::Stream::SeekType whence,
		              in SearchOption            optionmask)
                                                  raises (OptionNotSupported);
	};


	interface EditorView {

		exception OutOfRange {};

		struct Position {
			long character;
			long row;
			long column;
		};

		struct Range {
			Position start;
			Position end;
		};

		/**
		 * set_stream:
		 * @stream: A Gnome::Stream containing the data the view should display
		 *
		 * This method gets called by a Desktop::Editor if the ViewType isn't
		 * locally supported by the editor, meaning that this view is
		 * an external process. Note: editors do not need to support this.
		 */
		void set_stream (in Gnome::Stream stream);

		/**
		 * changed:
		 *
		 * This method gets called when the contents of the data in the
		 * editor change and this is an external EditorView.
		 */
		void changed ();

		/**
		 * get_pos:
		 *
		 * Returns the current position of the cursor in the
		 * Editor view.
		 */
		Position get_pos ();
		/**
		 * scroll_pos:
		 * @offset: how much to scroll
		 * @whence: scroll from where
		 *
		 * This method allows you change the position of the cursor
		 * in the editor window. If @offset's character field is non-zero, 
		 * that will be used to scroll on a character basis. Otherwise
		 * the line field will be used to scroll on a line basis.
		 * the column field is ignored.
		 *
		 * Returns the cursor position after the scroll.
		 */
		Position scroll (in Position                offset,
		                 in GNOME::Stream::SeekType whence) raises (OutOfRange);
		/**
		 * get_selection:
		 *
		 * Returns the range of the current selection.
		 */
		Range get_selection ();

		/**
		 * set_selection:
		 * @selection: A Range indicating what to select
		 *
		 * Sets the current selection in the view to @selection
		 */
		void set_selection (in Range selection);
	};


	/* This interface should also implement the GNOME::PersistFile
	 * and GNOME::PersistStream interfaces
	 */
	interface Editor : GNOME::Unknown {
		exception MultipleViewsNotSupported {};
		exception ViewTypeNotSupported {};
		/**
		 * access_as_stream:
		 *
		 * Returns a GNOME::Stream object through which you can
		 * manipulate the contents of the editor.
		 */
		GNOME::Stream access_as_stream ();

		/**
		 * new_view:
		 * @repo_id: The repo_id of the type of view requested
		 * @use_existing: Use an already existing view if available
		 *
		 * Returns a view of type @repo_id
		 */
		Object get_view(in string repo_id, in boolean use_existing)
		                                      raises (MultipleViewsNotSupported,
		                                              ViewTypeNotSupported);

		/**
		 * convert_pos:
		 * @position: a character-based position
		 *
		 * Converts @position into a Desktop::EditorViewer::Position
		 * so you can see what the corresponding line and column are.
		 */
		EditorView::Position convert_pos (in long position);
	};
};

-- 
Martijn van Beers  <martijn@earthling.net>

'Don't worry if it sounds odd. Believe me, you are talking to
someone who has seen a lot of stuff that is odd. And I don't
mean biscuits.' --- Arthur Dent