Changeset 51257 in vbox for trunk/doc

Timestamp:

May 15, 2014 12:04:17 PM (11 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

93716

Message:

DnD: Documentation, misc general typos + todos.

Location:

trunk/doc/manual/en_US

Files:

• user_BasicConcepts.xml (modified) (13 diffs)
• user_GuestAdditions.xml (modified) (1 diff)
• user_VBoxManage.xml (modified) (12 diffs)

trunk/doc/manual/en_US/user_BasicConcepts.xml

@@ -370 +370 @@
       <para><glosslist>
           <glossentry>
-            <glossterm>Snapshot folder</glossterm>
+            <glossterm>Snapshot Folder</glossterm>
 
             <glossdef>
@@ -381 +381 @@
 
           <glossentry>
-            <glossterm>Shared clipboard</glossterm>
+            <glossterm>Shared Clipboard</glossterm>
 
             <glossdef>
@@ -396 +396 @@
               details.</para>
 
-            <para>The shared clipboard is disabled by default. See
+              <para>The shared clipboard is disabled by default. See
               <xref linkend="security_clipboard"/> for an explanation. This
               setting can be changed at any time using the "Shared Clipboard"
@@ -406 +406 @@
             <glossterm>Drag'n'Drop</glossterm>
             <glossdef>
-              <para>This setting allows to enable Drag and Drop: Select a file
-                on the desktop, click the left mouse button, move the mouse
-                to the VM window and release the mouse button. The file is
-                copied from the host to the guest. This feature is currently
-                only implemented for Linux guests and only for copying files
-                from the host to the guest.<footnote><para>Support
-                for Drag'n'Drop was added with VirtualBox 4.2</para></footnote></para>
+              <para>This setting allows to enable support for drag'n drop: Select
+              an object (e.g. a file) from the host or guest and directly copy
+              or open it on the guest or host. Multiple per-VM drag'n drop modes
+              allow restricting access in either direction.</para>
+
+              <para>For drag'n drop to work the Guest Additions need to be
+              installed on the guest.</para>
+
+              <note>Drag'n drop is disabled by default. This setting can be
+              changed at any time using the "Drag'n'Drop" menu item in the
+              "Devices" menu of the virtual machine.</note>
+
+              <para>See <xref linkend="guestadd-dnd"/> for more information.</para>
+
+              <footnote><para>Experimental support for drag and drop was added
+              with VirtualBox 4.2.</para></footnote>
             </glossdef>
           </glossentry>
 
           <glossentry>
-            <glossterm>Removable media: remember runtime changes</glossterm>
-
+            <glossterm>Removable Media</glossterm>
             <glossdef>
               <para>If this is checked, VirtualBox will save the state of what
-              media has been mounted between several runs of a virtual
-              machine.</para>
+              media has been mounted between several runs of a virtual machine.</para>
             </glossdef>
           </glossentry>
 
           <glossentry>
-            <glossterm>Mini toolbar</glossterm>
-
+            <glossterm>Mini ToolBar</glossterm>
             <glossdef>
               <para>In full screen or seamless mode, VirtualBox can display a
@@ -717 +723 @@
           as of the activation of <emphasis>3D acceleration</emphasis> and
           <emphasis>2D video acceleration</emphasis>. A rough estimate
-          is (<emphasis>color depth</emphasis> / 8) x 
+          is (<emphasis>color depth</emphasis> / 8) x
           <emphasis>vertical pixels</emphasis> x
           <emphasis>horizontal pixels</emphasis> x
@@ -1027 +1033 @@
     equipped with one or two serial ports (also called COM ports by DOS and
     Windows). Serial ports were commonly used with modems, and some
-    computer mice used to be connected to serial ports before USB became 
-    commonplace. 
+    computer mice used to be connected to serial ports before USB became
+    commonplace.
     </para>
 
@@ -1042 +1048 @@
     <para>If a virtual serial port is enabled, the guest operating system sees
     a standard 16550A compatible UART device. Both receiving and transmitting
-    data is supported. How this virtual serial port is then connected to the 
+    data is supported. How this virtual serial port is then connected to the
     host is configurable, and the details depend on your host operating system.
     </para>
@@ -1053 +1059 @@
     <computeroutput>--uartmode</computeroutput> options.</para>
 
-    <para>In either case, you can configure up to two virtual serial ports per 
+    <para>In either case, you can configure up to two virtual serial ports per
     virtual machine. For each such device, you will need to
     determine<orderedlist>
@@ -1113 +1119 @@
                       <para>On a Windows host, data will be sent and received
                       through a named pipe. The pipe name must be in the format
-                      <computeroutput>\\.\pipe\&lt;name&gt;</computeroutput> 
+                      <computeroutput>\\.\pipe\&lt;name&gt;</computeroutput>
                       where <computeroutput>&lt;name&gt;</computeroutput> should
-                      identify the virtual machine but may be freely 
-                      chosen.</para> 
+                      identify the virtual machine but may be freely
+                      chosen.</para>
                       <para>For forwarding serial traffic, you can use a helper
                       program called VMware Serial Line Gateway, available for
@@ -1132 +1138 @@
                       <para>On a Mac, Linux or Solaris host, a local
                       domain socket is used instead. The socket filename must be
-                      chosen such that the user running VirtualBox has 
-                      sufficient privileges to create and write to it. The 
-                      <computeroutput>/tmp</computeroutput> directory is often a 
+                      chosen such that the user running VirtualBox has
+                      sufficient privileges to create and write to it. The
+                      <computeroutput>/tmp</computeroutput> directory is often a
                       good candidate.</para>
-                      <para>On Linux there are various tools which can connect 
-                      to a local domain socket or create one in server mode. The 
+                      <para>On Linux there are various tools which can connect
+                      to a local domain socket or create one in server mode. The
                       most flexible tool is
                       <computeroutput>socat</computeroutput> and is available
@@ -1153 +1159 @@
 
                 <para>For a direct connection between two virtual machines
-                (corresponding to a null-modem cable), simply configure one VM 
+                (corresponding to a null-modem cable), simply configure one VM
                 to create a pipe/socket and another to attach to it.
                 </para>
@@ -1159 +1165 @@
 
               <listitem>
-                <para>You can send the virtual serial port output to a file. 
-                This option is very useful for capturing diagnostic output from 
-                a guest. Any file may be used for this purpose, as long as the 
-                user running VirtualBox has sufficient privileges to create and 
+                <para>You can send the virtual serial port output to a file.
+                This option is very useful for capturing diagnostic output from
+                a guest. Any file may be used for this purpose, as long as the
+                user running VirtualBox has sufficient privileges to create and
                 write to the file.
                 </para>
@@ -1168 +1174 @@
             </itemizedlist></para>
         </listitem>
-      </orderedlist>Up to two serial ports can be configured per virtual 
+      </orderedlist>Up to two serial ports can be configured per virtual
       machine, but you can pick any port numbers out of the above. However,
-      serial ports cannot reliably share interrupts; if both ports are to be 
-      used at the same time, they must use different interrupt levels, for 
+      serial ports cannot reliably share interrupts; if both ports are to be
+      used at the same time, they must use different interrupt levels, for
       example COM1 and COM2, but not COM1 and COM3.
     </para>

trunk/doc/manual/en_US/user_GuestAdditions.xml

@@ -1246 +1246 @@
       manually.)</para>
     </sect2>
+  </sect1>
+
+  <sect1 id="guestadd-dnd">
+    <title>Drag'n Drop</title>
+
+    <para>Starting with version 4.4, VirtualBox supports to drag'n drop content
+    from the host to the guest and vice versa. For this to work the latest Guest
+    Additions must be installed on the guest.</para>
+
+    <para>Drag'n drop transparently allows copying or opening files, directories
+    and even certain clipboard formats from one end to the other, e.g. from the
+    host to the guest or from the guest to the host. One then can perform drag'n
+    drop operations between the host and a VM as it would be a native drag'n drop
+    operation on the host OS.</para>
+
+    <para>At the moment drag'n drop is implemented for Windows- and X-Windows-based
+    systems, both, on host and guest side. As X-Windows sports different drag'n drop
+    protocols only the most used one, XDND, is supported for now. Applications using
+    other protocols (such as Motif or OffiX) will not be recognized by VirtualBox.</para>
+
+    <para>In context of using drag'n drop the origin of the data is called
+    <emphasis role="bold">source</emphasis>, that is, where the actual data comes
+    from and is specified. On the other hand there is the
+    <emphasis role="bold">target</emphasis>, which specifies where the data from
+    the source should go to. Transferring data from the source to the target can
+    be done in various ways, e.g. copying, moving or linking.<footnote><para>At
+    the moment VirtualBox only copying data is supported. Moving or linking from
+    data currently is not implemented yet.</para></footnote></para>
+
+    <para>When transferring data from the host to the guest OS, the host in this
+    case is the source, whereas the guest OS is the target. However, when doing
+    it the other way around, that is, transferring data from the guest OS to the
+    host, the guest OS this time became the source and the host is the target.</para>
+
+    <para>For security reasons drag'n drop can be configured at runtime
+    on a per-VM basis either using the "Drag'n'Drop" menu item in the "Devices" menu
+    of the virtual machine or VBoxManage: The following four modes are available:
+
+    <para><mediaobject>
+      <imageobject>
+        <imagedata align="center" fileref="images/dnd-modes.png"
+                   width="10cm" />
+        </imageobject>
+      </mediaobject></para>
+
+    <itemizedlist>
+      <listitem>
+        <para><emphasis role="bold">Disabled</emphasis> disables the drag'n drop
+        entirely. This is the default when creating new VMs.</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold">Host To Guest</emphasis> enables performing
+        drag'n drop operations from the host to the guest only.</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold">Guest To Host</emphasis> enables performing
+        drag'n drop operations from the guest to the host only.</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold">Bidirectional</emphasis> enables performing
+        drag'n drop operations to both directions, e.g. from the host to the guest
+        and vice versa.</para>
+      </listitem>
+    </itemizedlist></para>
+
+    <note><para>Drag'n drop support depends on the frontend being used; at the
+    moment only the VirtualBox Manager frontend provides this
+    functionality.</para></note>
+
+    <para>To use VBoxManage for controlling the current drag'n drop mode, see <xref
+    linkend="vboxmanage" />. The commands <computeroutput>modifyvm</computeroutput>
+    and <computeroutput>controlvm</computeroutput> allow setting the VM's current
+    drag'n drop mode via command line.</para>
+
+    <sect2 id="guestadd-dnd-formats">
+      <title>Supported formats</title>
+
+      <para>As VirtualBox can run on a variety of host OSes and also supports a wide
+      range of guests, certain data formats must be translated after those
+      got transfered over so that the target OS (that is, the side which receiving the
+      data) is able to handle them in an appropriate manner.</para>
+
+      <note><para>When dragging files however, no data conversion is done in any way, e.g.
+      when transferring a file from a Linux guest to a Windows host the Linux-specific
+      line endings won't be converted to Windows ones.</para></note>
+
+      <para>The following formats are handled by the VirtualBox drag'n drop service:
+        <itemizedlist>
+          <listitem>
+            <para><emphasis role="bold">Plain text</emphasis>, from applications such as
+            text editors, internet browsers and terminal windows</para>
+          </listitem>
+          <listitem>
+            <para><emphasis role="bold">Files</emphasis>, from file managers such
+            as Windows explorer, Nautilus and Finder</para>
+          </listitem>
+          <listitem>
+            <para><emphasis role="bold">Directories</emphasis>, where the same applies
+            as for files</para>
+          </listitem>
+        </itemizedlist>
+      </para>
+    </sect2>
+
   </sect1>
 

trunk/doc/manual/en_US/user_VBoxManage.xml

@@ -938 +938 @@
 
     <sect2 id="vboxmanage-modifyvm-other">
-      <title>Serial port, audio, clipboard and USB settings</title>
-
-      <para>The following other hardware settings are available through
+      <title>Miscellaneous settings</title>
+
+      <para>The following other hardware settings, such as serial port, audio,
+      clipboard, drag'n drop, monitor and USB settings are available through
       <computeroutput>VBoxManage modifyvm</computeroutput>:<itemizedlist>
           <listitem>
@@ -1008 +1009 @@
             <para><computeroutput>--clipboard
             disabled|hosttoguest|guesttohost|bidirectional</computeroutput>:
-            With this setting, you can select whether the guest operating
-            system's clipboard should be shared with the host; see <xref
-            linkend="generalsettings" />. This requires that the Guest
+            With this setting, you can select if and how the guest or host
+            operating system's clipboard should be shared with the host or guest;
+            see <xref linkend="generalsettings" />. This requires that the Guest
+            Additions be installed in the virtual machine.</para>
+          </listitem>
+
+          <listitem>
+            <para><computeroutput>--draganddrop
+            disabled|hosttoguest|guesttohost|bidirectional</computeroutput>:
+            With this setting, you can select the current drag'n drop mode
+            being used between the host and the virtual machine;
+            see <xref linkend="guestadd-dnd" />. This requires that the Guest
             Additions be installed in the virtual machine.</para>
           </listitem>
@@ -1032 +1042 @@
           </listitem>
         </itemizedlist></para>
+
+        <!-- @todo r=andy Document tracing-* commands -->
     </sect2>
 
@@ -1048 +1060 @@
             default.</para>
           </listitem>
+
+          <!-- @todo r=andy Document vrdeproperty -->
 
           <listitem>
@@ -1510 +1524 @@
 
     <itemizedlist>
+      <!-- @todo r=andy Document keyboardputscancode -->
+
       <listitem>
         <para>The <computeroutput>setlinkstate&lt;1-N&gt;</computeroutput>
@@ -1534 +1550 @@
 
       <listitem>
+        <para>With the "nictrace" options, you can optionally trace
+        network traffic by dumping it to a file, for debugging
+        purposes.</para>
+
+        <para>With <computeroutput>--nictrace&lt;1-N&gt;
+        on|off</computeroutput>, you can enable network tracing for a
+        particular virtual network card.</para>
+
+        <para>If enabled, you must specify with
+        <computeroutput>--nictracefile&lt;1-N&gt;
+        &lt;filename&gt;</computeroutput> what file the trace should be
+        logged to.</para>
+      </listitem>
+
+      <!-- @todo r=andy Document nicpromisc -->
+
+      <listitem>
+        <para><computeroutput>nicproperty&lt;1-N&gt;
+        &lt;paramname&gt;="paramvalue"</computeroutput>:
+        This option, in combination with "nicgenericdrv" allows you to
+        pass parameters to rarely-used network backends.</para><para>
+        Those parameters are backend engine-specific, and are different
+        between UDP Tunnel and the VDE backend drivers. For example,
+        please see <xref linkend="network_udp_tunnel" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>The <computeroutput>guestmemoryballoon</computeroutput>
+        operation changes the size of the guest memory balloon, that is,
+        memory allocated by the VirtualBox Guest Additions from the guest
+        operating system and returned to the hypervisor for re-use by other
+        virtual machines. This must be specified in megabytes. For details,
+        see <xref linkend="guestadd-balloon" />.</para>
+      </listitem>
+
+      <listitem>
         <para><computeroutput>usbattach</computeroutput> and
         <computeroutput>usbdettach</computeroutput> make host USB devices
@@ -1542 +1595 @@
         <para>You can use <computeroutput>VBoxManage list
         usbhost</computeroutput> to locate this information.</para>
+      </listitem>
+
+      <listitem>
+        <para><computeroutput>clipboard
+        disabled|hosttoguest|guesttohost|bidirectional</computeroutput>:
+        With this setting, you can select if and how the guest or host
+        operating system's clipboard should be shared with the host or guest;
+        see <xref linkend="generalsettings" />. This requires that the Guest
+        Additions be installed in the virtual machine.</para>
+      </listitem>
+
+      <listitem>
+        <para><computeroutput>draganddrop
+        disabled|hosttoguest|guesttohost|bidirectional</computeroutput>:
+        With this setting, you can select the current drag'n drop mode
+        being used between the host and the virtual machine;
+        see <xref linkend="guestadd-dnd" />. This requires that the Guest
+        Additions be installed in the virtual machine.</para>
       </listitem>
 
@@ -1558 +1629 @@
       </listitem>
 
+
       <listitem>
         <para><computeroutput>setvideomodehint</computeroutput> requests that
@@ -1570 +1642 @@
       </listitem>
 
+      <!-- @todo r=andy Document vcpenabled + vcpscreens! -->
+
       <listitem>
         <para>The <computeroutput>setcredentials</computeroutput> operation is
@@ -1576 +1650 @@
       </listitem>
 
+      <!-- @todo r=andy Document teleport! -->
+
       <listitem>
-        <para>The <computeroutput>guestmemoryballoon</computeroutput>
-        operation changes the size of the guest memory balloon, that is,
-        memory allocated by the VirtualBox Guest Additions from the guest
-        operating system and returned to the hypervisor for re-use by other
-        virtual machines. This must be specified in megabytes. For details,
-        see <xref linkend="guestadd-balloon" />.</para>
+        <para><computeroutput>--plugcpu|unplugcpu
+        &lt;id&gt;</computeroutput>: If CPU hot-plugging is enabled, this adds
+        a virtual CPU to the virtual machines (or removes one).
+        <computeroutput>&lt;id&gt;</computeroutput> specifies the index of
+        the virtual CPU to be added or removed and must be a number from 0
+        to the maximum no. of CPUs configured. CPU 0 can never be removed.</para>
       </listitem>
 
@@ -1591 +1667 @@
         can use up to 50% of a single host CPU.</para>
       </listitem>
+
+      <!-- @todo r=andy Document webcam! -->
+
     </itemizedlist>
   </sect1>
@@ -2733 +2812 @@
     <title>VBoxManage guestcontrol</title>
 
-    <para>The "guestcontrol" commands allow you to control certain things
-    inside a guest from the host. Please see <xref
+    <para>The <computeroutput>guestcontrol</computeroutput> commands allow you
+    to control certain things inside a guest from the host. Please see <xref
     linkend="guestadd-guestcontrol" /> for an introduction.</para>