Changeset 2540 in vbox for trunk/src/VBox/Main/idl

Timestamp:

May 8, 2007 4:06:27 PM (18 years ago)

Author:

vboxsync

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

20981

Message:

Main & All Frontends: Improved console window activation helper APIs (still no success on X11, works well on Win32, the old method of activation is disabled).

File:

• trunk/src/VBox/Main/idl/VirtualBox.xidl (modified) (5 diffs)

trunk/src/VBox/Main/idl/VirtualBox.xidl

@@ -2585 +2585 @@
         <method name="showConsoleWindow">
             <desc>
-                Returns @c true if the VM console process can activate the
-                console window and bring it to foreground on the desktop of
-                the host PC.
+                Activates the console window and brings it to foreground on
+                the desktop of the host PC. Many modern window managers on
+                many platforms implement some sort of focus stealing
+                prevention logic, so that it may be impossible to activate
+                a window without the help of the currently active
+                application. In this case, this method will return a non-zero
+                identifier that represents the top-level window of the VM
+                console process. The caller, if it represents a currently
+                active process, is responsible to use this identifier (in a
+                platform-dependent manner) to perform actual window
+                activation.
                 <note>
                     This method will fail if a session for this machine is not
@@ -2593 +2601 @@
                 </note>
             </desc>
+            <param name="winId" type="unsigned long long" dir="return">
+                <desc>
+                  Platform-dependent identifier of the top-level VM console
+                  window, or zero if this method has performed all actions
+                  necessary to implement the <i>show window</i> semantics for
+                  the given platform and/or VirtualBox front-end.
+                </desc>
+            </param>
         </method>
 
@@ -2819 +2835 @@
                 method should return a failure.
 
+                Note that many modern window managers on many platforms
+                implement some sort of focus stealing prevention logic, so
+                that it may be impossible to activate a window without the
+                help of the currently active application (which is supposedly
+                an initiator of this notification). In this case, this method
+                must return a non-zero identifier that represents the
+                top-level window of the VM console process. The caller, if it
+                represents a currently active process, is responsible to use
+                this identifier (in a platform-dependent manner) to perform
+                actual window activation.
+
+                This method must set @a winId to zero if it has performed all
+                actions necessary to complete the request and the console
+                window is now active and in foreground, to indicate that no
+                further action is required on the caller's side.
+
                 <note>
                     This notification is not designed to be implemented by
@@ -2828 +2860 @@
                 </note>
             </desc>
+            <param name="winId" type="unsigned long long" dir="return">
+                <desc>
+                    Platform-dependent identifier of the top-level VM console
+                    window, or zero if this method has performed all actions
+                    necessary to implement the <i>show window</i> semantics for
+                    the given platform and/or this VirtualBox front-end.
+                </desc>
+            </param>
         </method>
 
@@ -7415 +7455 @@
             <param name="check" type="boolean" dir="in"/>
             <param name="canShow" type="boolean" dir="out"/>
+            <param name="winId" type="unsigned long long" dir="out"/>
         </method>