<chapter id="gui_objtreepropedit_id" xreflabel="Object tree and property editor">
	<title>Object tree, Stream, Selection and Property editor</title>
	<para>
	  The right side of PdfEditor consists of two main parts <emphasis>Object tree</emphasis> and <emphasis>Property editor</emphasis>. 
	  It can be further specialized to <emphasis>Selection</emphasis> and <emphasis>Stream</emphasis> windows.
	</para>
	
	<para>
	  Pdf file consists of objects which form a tree-like structure. There are seven simple objects 
	  <itemizedlist mark="opencircle">
		<listitem><para>null</para></listitem>
		<listitem><para>boolean</para></listitem>
		<listitem><para>integer</para></listitem>
		<listitem><para>real</para></listitem>
		<listitem><para>string</para></listitem>
		<listitem><para>name</para></listitem>
		<listitem><para>reference</para></listitem>
	  </itemizedlist>
	  and three complex
	  <itemizedlist mark="opencircle">
		<listitem><para>array</para></listitem>
		<listitem><para>dictionary</para></listitem>
		<listitem><para>stream</para></listitem>
	  </itemizedlist>
	  Object tree displays the tree-like object hierarchy starting at the most important objects and 
	  Property editor displays the contents of selected object in human readable form and allows editing the objects in raw form.
	</para>
	 
	<para>
	  There is one important object called content stream which consists of many small operators and their operands. Everything visible
	  on a page is in these content streams. Pdf operators are the objects that contorl what is displayed on a page.
	  The content stream is shown in Stream window in human editable form.
    </para>
	  
	<para>
	Last tool used to display objects is the Selection window. When some operators are selected using selection modes, those operators
	are displayed in the Selection window.
	</para>
	  
      <mediaobject>
		  <imageobject><imagedata fileref="gui/images/propedit_all.png" format="PNG"/></imageobject>
		  <caption><para>Object tree, Stream, Selection and Property editor</para></caption>
      </mediaobject>

	<sect1 id="purpose_and_usage">
	<title>Purpose and usage</title>
	<para>
	  The purpose of these windows is to enable complete control over pdf objects and structure of a pdf file. 
	  It shows raw pdf objects in user friendly way with the possibility to traverse the objects using the tree like
	  structure, select special category of operators and perform operation on resulting set, see exactly which operators
	  were selected using graphical selection tools. It also allows editing raw objects which mostly requires knowledge of the pdf standard.
	 </para>
	 <para>
	  We gain complete control over pdf file with this tool. It can be used for 
	  advanced editing that almost makes PdfEditor a pdf creator. With the description of operators, object type
	  highlighting and object importance visualization this tool can be also used by normal users for simple
	  but powerful editions.
	  We can add and delete objects almost at will (some top level objects are just for more human readibility and
	  can be neither deleted nor added.)
	</para>
	</sect1>

    <sect1 id="object_tree_start_objects">
	<title>Object tree start objects</title>
	<para>
	There are three main objects in the object tree. 
	  <itemizedlist mark="opencircle">
		<listitem><para>Catalog</para></listitem>
		<listitem><para>Pages</para></listitem>
		<listitem><para>Outlines</para></listitem>
	  </itemizedlist>
	Catalog object is the start point of all objects. Any object can be reached from Catalog. Pages and Outlines are just
	shortcuts for special objects somewhere deep in Catalog object.
	</para>
	
	    <sect2 id="obj_catalog">
		<title>Catalog</title>
		<para>
		Root object of all objects.
			  <mediaobject>
				  <imageobject><imagedata fileref="gui/images/propedit_catalog.png" format="PNG"/></imageobject>
				  <caption><para>Catalog</para></caption>
			  </mediaobject>
		</para>
		</sect2>	

	    <sect2 id="obj_pages">
		<title>Pages</title>
		<para>
		Set of all pages and it is a shortcut to all page dictionaries.
			  <mediaobject>
				  <imageobject><imagedata fileref="gui/images/propedit_pages.png" format="PNG"/></imageobject>
				  <caption><para>Pages</para></caption>
			  </mediaobject>
		</para>
		</sect2>
		
		<sect2 id="obj_outlines">
		<title>Outlines</title>
		<para>
		List of all outlines with the ability to edit the title.
			  <mediaobject>
				  <imageobject><imagedata fileref="gui/images/propedit_outlines.png" format="PNG"/></imageobject>
				  <caption><para>Outlines</para></caption>
			  </mediaobject>
		</para>
		</sect2>

	</sect1>

	<sect1 id="adding_deleting_objects">
		<title>Adding and deleting objects</title>
		<para>
		This feature is for very advanced users. Object tree can be used to to add and delete objects, stream and selection 
		to delete objects. User can choose the type of object which to add. Deletion of pdf operator operands is not allowed 
		because in most cases the result would be an invalid content stream.
		</para>
		
		<sect2 id="creating_pdf_files">
		<title>Creating pdf files</title>
		<para>
		The adding object feature can be used to create completely new pdf files. With the help of scripting, PdfEditor can 
		be used as pdf creator. The advantage is that we can use arbitrary empty template pdf file created by any drawing tool and 
		PdfEditor to add objects into it. The creation of pdf files containing text is limited because we do not support our own
		fonts only standard ones.
		</para>
		</sect2>
	</sect1>

	<sect1 id="controls">
	<title>Controls</title>
	<para>
	There are two ways how to to open, close and select objects. We can use either mouse or arrows. Up/down is used to 
	go one object above/below current and right/left is used to open/close complex objects. 
	</para>
	
	<para>
	When an object is selected
	right mouse click opens a menu with operations we can perform on the object according to its type.
	  <mediaobject>
		  <imageobject><imagedata fileref="gui/images/propedit_rclick.png" format="PNG"/></imageobject>
		  <caption><para>Mouse right click menu</para></caption>
	  </mediaobject>
	</para>
	
	<para>
	We can add properties/objects using Insert key or clicking
	  <mediaobject>
		  <imageobject><imagedata fileref="gui/images/propedit_edit_add.png" format="PNG"/></imageobject>
		  <caption><para>Add button</para></caption>
	  </mediaobject>
	button and delete properties/objects pressing Delete key or clicking 
	  <mediaobject>
		  <imageobject><imagedata fileref="gui/images/propedit_edit_del.png" format="PNG"/></imageobject>
		  <caption><para>Delete button</para></caption>
	  </mediaobject>
	button. Not always is adding and deleting possible.
	</para>
	</sect1>

	<sect1 id="multiselect">
		<title>Multiselect</title>
		<para>
		We can use multiselect to select more objects and to perform specific action on all of them. We can use this
		feature in all mentioned tools (Object tree, Selection, Stream). This can dramatically increase speed of editing.
		  <mediaobject>
			  <imageobject><imagedata fileref="gui/images/propedit_multiselection.png" format="PNG"/></imageobject>
			  <caption><para>Multiselect</para></caption>
		  </mediaobject>
		</para>
	</sect1>

	<sect1 id="object_tree">
	<title>Object tree</title>
	<para>
	There are many special objects. You can specify which of them to display and which not. And whether crucial objects
	should be locked to changes.
	In menu click Tools->Options and select Editor tab. In order to take effect reload the object tree.
	  <mediaobject>
		  <imageobject><imagedata fileref="gui/images/propedit_opt_editor.png" format="PNG"/></imageobject>
		  <caption><para>Editor options</para></caption>
	  </mediaobject>
	In menu click Tools->Options and select Object tree tab. In order to take effect reload the object tree.
	  <mediaobject>
		  <imageobject><imagedata fileref="gui/images/propedit_opt_objtree.png" format="PNG"/></imageobject>
		  <caption><para>Object tree display options</para></caption>
	  </mediaobject>

	</para>

		<sect2 id="property_mode">
		<title>Property mode</title>
		<para>
		Many pdf objects are compulsory or must contain required entries or have specified values. Incompetent manipulation
		with these objects can result in invalid pdf files or non predictable output. Therefore a mode is assigned to every
		property which indicates the importance of the property. There are 

	 <itemizedlist mark="opencircle">
		<listitem><para>Unknown - mode not known</para></listitem>
		<listitem><para>Normal - normal property, editing should not harm</para></listitem>
		<listitem><para>Hidden - not crucial property, editing should not harm</para></listitem>
		<listitem><para>Read only - not property, manual editing does not make sense</para></listitem>
		<listitem><para>Advanced - crucial property, incompetent editing can make harm </para></listitem>
	  </itemizedlist>
		When mouse cursor is over a property the property mode is displayed as text in the status bar. Hidden, read only and advanced
		tincture property colour to blue, gray and red. It depends on the theme used.
		  <mediaobject>
			  <imageobject><imagedata fileref="gui/images/propedit_impor.png" format="PNG"/></imageobject>
			  <caption><para>Visualization of object mode</para></caption>
		  </mediaobject>
		</para>
		<para>
		These settings are stored in <emphasis>mode.conf</emphasis> file which can be easily modified to match user own pdf skills.
		</para>
		</sect2>


		<sect2 id="adding_deleting_properties">
		<title>Adding and deleting properties</title>
		<para>
		 Adding and deleting objects in the object tree is possible.
		 There are two keyboard shortcuts for this, <keycap>Insert</keycap> of adding, <keycap>Delete</keycap> for deleting
		</para>
		</sect2>
	
	</sect1>

	<sect1 id="property_editor">
	<title>Property editor</title>
	<para>
	</para>

		<sect2 id="edit_properties">
		<title>Editing properties</title>
		<para>
		Each pdf object has simple value or set of values which can be changed. Almost all pdf operators have
		operands which are normal pdf objects which can be changed. Implicit changing of object types is not allowed (e.g. integer
		object to string etc.) but this can be done by deleting and adding desired property type. When changing integer object only
		integers are accepted, when changing boolean values only true/false is accepted etc.
		  <mediaobject>
			  <imageobject><imagedata fileref="gui/images/propedit_edit.png" format="PNG"/></imageobject>
			  <caption><para>Editing a property</para></caption>
		  </mediaobject>
		When editing a reference number a dialog appears which verifies whether a pdf object with specified reference number exists.
		  <mediaobject>
			  <imageobject><imagedata fileref="gui/images/propedit_edit_ref.png" format="PNG"/></imageobject>
			  <caption><para>Text selection</para></caption>
		  </mediaobject>
		</para>

		<para>
		To make a change visible perform these steps
		 <itemizedlist mark="opencircle">
			<listitem><para>edit the object value</para></listitem>
			<listitem><para>press enter or click away from the property</para></listitem>
			<listitem><para>reload page if the change is visible</para></listitem>
		  </itemizedlist>
		</para>
		</sect2>

	</sect1>

	<sect1 id="selection">
	<title>Selection</title>
	<para>
	PdfEditor allows selecting specific operators easily using selection modes. There are two main object selection modes namely
	text selection and graphical object selection. The third way how to select objects is using multiselect which allows us to 
	manually select more objects. Selection is very useful when performing an action on many objects (e.g. deleting...)
	</para>

		<sect2 id="text_selection">
		<title>Text selection</title>
		<para>
		When this mode is selected we can select only text objects. 
		  <mediaobject>
			  <imageobject><imagedata fileref="gui/images/propedit_text_selection.png" format="PNG"/></imageobject>
			  <caption><para>Text selection</para></caption>
		  </mediaobject>
	   </para>
	   
	   <para>
		  Note: TrueType fonts use pictures to draw letters and that makes it very difficult to compute the height of
		  the letter. The height of a true type letter can be incorrect.
		</para>
		</sect2>

		<sect2 id="graphical_selection">
		<title>Graphical objects selection</title>
		<para>
		When this mode is selected we can select only graphical objects. Many pdf creators are putting strange invisible 
		graphical objects to page so sometimes it is difficult to select the right graphical object.
		  <mediaobject>
			  <imageobject><imagedata fileref="gui/images/propedit_gfx_selection.png" format="PNG"/></imageobject>
			  <caption><para>Graphical object selection</para></caption>
		  </mediaobject>
		</para>
		</sect2>

		<sect2 id="deleting objects">
		<title>Deleting objects</title>
		<para>
		 Press <keycap>Delete</keycap> key to delete selected objects.
		</para>
		</sect2>


	</sect1>

	<sect1 id="stream">
	<title>Stream</title>

	<para>
	Page is drawn by executing operations which are equal to small changes. These changes are stored in content stream of a page.
	You can display these operations by clicking Pages->Page #->Stream # in Object tree. New tab is displayed which shows pdf operators
	and their operands.
		  <mediaobject>
			  <imageobject><imagedata fileref="gui/images/propedit_stream.png" format="PNG"/></imageobject>
			  <caption><para>Stream</para></caption>
		  </mediaobject>
	</para>

		<sect2 id="operator_description">
		<title>Operator description</title>
		<para>
		As mentioned above, operators control what is displayed on a page. For advanced editing, it is crucial to be able
		to change them. For non advanced users the operator tags are not very intuitive so a human description of each operator
		is shown in the status bar.
		  <mediaobject>
			  <imageobject><imagedata fileref="gui/images/propedit_op_desc.png" format="PNG"/></imageobject>
			  <caption><para>Operator description</para></caption>
		  </mediaobject>
		</para>
		<para>
		The definition of the operators is stored in <emphasis>operator.hint</emphasis> and can be edited freely.
		</para>
		</sect2>

		<sect2 id="operator_modes">
		<title>Operator modes</title>
		<para>
		There many operators but only few worth changing manually. To allow fast search of these operators, operator modes were
		designed. After selecting one of the operator modes in Stream window, only those operators are shown. Currently there are
		four operator modes
		 <itemizedlist mark="opencircle">
			<listitem><para>operators</para></listitem>
			<listitem><para>text operators</para></listitem>
			<listitem><para>font operators</para></listitem>
			<listitem><para>graphical objects iterators</para></listitem>
		  </itemizedlist>

		  <mediaobject>
			  <imageobject><imagedata fileref="gui/images/propedit_op_modes.png" format="PNG"/></imageobject>
			  <caption><para>Operator modes</para></caption>
		  </mediaobject>
		</para>
		</sect2>
	
		<sect2 id="add_delete_properties">
		<title>Adding and deleting properties</title>
		<para>
		Only deleting is possible.
		</para>
		</sect2>

	</sect1>

</chapter>