xpfe/appshell/public/nsIWindowMediator.idl@b8a032363ba2 (annotated)
xpfe/appshell/public/nsIWindowMediator.idl
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
| michael@0 | 1 | /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ |
| michael@0 | 2 | /* This Source Code Form is subject to the terms of the Mozilla Public |
| michael@0 | 3 | * License, v. 2.0. If a copy of the MPL was not distributed with this |
| michael@0 | 4 | * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ |
| michael@0 | 5 | |
| michael@0 | 6 | #include "nsISupports.idl" |
| michael@0 | 7 | #include "nsISimpleEnumerator.idl" |
| michael@0 | 8 | |
| michael@0 | 9 | %{C++ |
| michael@0 | 10 | #define NS_WINDOWMEDIATOR_CID \ |
| michael@0 | 11 | { 0x79a2b7cc, 0xf05b, 0x4605, \ |
| michael@0 | 12 | { 0xbf, 0xa0, 0xfa, 0xc5, 0x4f, 0x27, 0xee, 0xc8 } } |
| michael@0 | 13 | |
| michael@0 | 14 | #define NS_WINDOWMEDIATOR_CONTRACTID \ |
| michael@0 | 15 | "@mozilla.org/appshell/window-mediator;1" |
| michael@0 | 16 | %} |
| michael@0 | 17 | |
| michael@0 | 18 | interface nsIXULWindow; |
| michael@0 | 19 | interface nsIWidget; |
| michael@0 | 20 | interface nsIDOMWindow; |
| michael@0 | 21 | interface nsIWindowMediatorListener; |
| michael@0 | 22 | |
| michael@0 | 23 | [scriptable, uuid(30cda5a1-a6df-4f32-9a73-0e59a32928c5)] |
| michael@0 | 24 | interface nsIWindowMediator: nsISupports |
| michael@0 | 25 | { |
| michael@0 | 26 | /** Return an enumerator which iterates over all windows of type aWindowType |
| michael@0 | 27 | * from the oldest window to the youngest. |
| michael@0 | 28 | * @param aWindowType the returned enumerator will enumerate only |
| michael@0 | 29 | * windows of this type. ("type" is the |
| michael@0 | 30 | * |windowtype| attribute of the XML <window> element.) |
| michael@0 | 31 | * If null, all windows will be enumerated. |
| michael@0 | 32 | * @return an enumerator of nsIDOMWindows. Note that windows close |
| michael@0 | 33 | * asynchronously in many cases, so windows returned from this |
| michael@0 | 34 | * enumerator can have .closed set to true. Caveat enumerator! |
| michael@0 | 35 | */ |
| michael@0 | 36 | nsISimpleEnumerator getEnumerator(in wstring aWindowType); |
| michael@0 | 37 | |
| michael@0 | 38 | /** Identical to getEnumerator except: |
| michael@0 | 39 | * @return an enumerator of nsIXULWindows |
| michael@0 | 40 | */ |
| michael@0 | 41 | nsISimpleEnumerator getXULWindowEnumerator(in wstring aWindowType); |
| michael@0 | 42 | |
| michael@0 | 43 | /** Return an enumerator which iterates over all windows of type aWindowType |
| michael@0 | 44 | * in their z (front-to-back) order. Note this interface makes |
| michael@0 | 45 | * no requirement that a window couldn't be revisited if windows |
| michael@0 | 46 | * are re-ordered while z-order enumerators are active. |
| michael@0 | 47 | * @param aWindowType the returned enumerator will enumerate only |
| michael@0 | 48 | * windows of this type. ("type" is the |
| michael@0 | 49 | * |windowtype| attribute of the XML <window> element.) |
| michael@0 | 50 | * If null, all windows will be enumerated. |
| michael@0 | 51 | * @param aFrontToBack if true, the enumerator enumerates windows in order |
| michael@0 | 52 | * from front to back. back to front if false. |
| michael@0 | 53 | * @return an enumerator of nsIDOMWindows |
| michael@0 | 54 | */ |
| michael@0 | 55 | nsISimpleEnumerator getZOrderDOMWindowEnumerator(in wstring aWindowType, |
| michael@0 | 56 | in boolean aFrontToBack); |
| michael@0 | 57 | |
| michael@0 | 58 | /** Identical to getZOrderDOMWindowEnumerator except: |
| michael@0 | 59 | * @return an enumerator of nsIXULWindows |
| michael@0 | 60 | */ |
| michael@0 | 61 | nsISimpleEnumerator getZOrderXULWindowEnumerator(in wstring aWindowType, |
| michael@0 | 62 | in boolean aFrontToBack); |
| michael@0 | 63 | |
| michael@0 | 64 | /** This is a shortcut for simply fetching the first window in |
| michael@0 | 65 | * front to back order. |
| michael@0 | 66 | * @param aWindowType return the topmost window of this type. |
| michael@0 | 67 | * ("type" is the |windowtype| attribute of |
| michael@0 | 68 | * the XML <window> element.) |
| michael@0 | 69 | * If null, return the topmost window of any type. |
| michael@0 | 70 | * @return the topmost window |
| michael@0 | 71 | */ |
| michael@0 | 72 | nsIDOMWindow getMostRecentWindow(in wstring aWindowType); |
| michael@0 | 73 | |
| michael@0 | 74 | /** |
| michael@0 | 75 | * Return the outer window with the given ID, if any. Can return null. |
| michael@0 | 76 | */ |
| michael@0 | 77 | nsIDOMWindow getOuterWindowWithId(in unsigned long long aOuterWindowID); |
| michael@0 | 78 | |
| michael@0 | 79 | /** |
| michael@0 | 80 | * Return the outer window with the given current window ID, if any. |
| michael@0 | 81 | * Can return null if no inner window with the ID exists or if it's not |
| michael@0 | 82 | * a current inner anymore. |
| michael@0 | 83 | */ |
| michael@0 | 84 | nsIDOMWindow getCurrentInnerWindowWithId(in unsigned long long aInnerWindowID); |
| michael@0 | 85 | |
| michael@0 | 86 | /** Add the window to the list of known windows. Listeners (see |
| michael@0 | 87 | * addListener) will be notified through their onOpenWindow method. |
| michael@0 | 88 | * @param aWindow the window to add |
| michael@0 | 89 | */ |
| michael@0 | 90 | [noscript] void registerWindow(in nsIXULWindow aWindow); |
| michael@0 | 91 | |
| michael@0 | 92 | /** Remove the window from the list of known windows. Listeners (see |
| michael@0 | 93 | * addListener) will be be notified through their onCloseWindow method. |
| michael@0 | 94 | * @param aWindow the window to remove |
| michael@0 | 95 | */ |
| michael@0 | 96 | [noscript] void unregisterWindow(in nsIXULWindow aWindow); |
| michael@0 | 97 | |
| michael@0 | 98 | /** Call this method when a window gains focus. It's a primitive means of |
| michael@0 | 99 | * determining the most recent window. It's no longer necessary and it |
| michael@0 | 100 | * really should be removed. |
| michael@0 | 101 | * @param aWindow the window which has gained focus |
| michael@0 | 102 | */ |
| michael@0 | 103 | [noscript] void updateWindowTimeStamp(in nsIXULWindow aWindow); |
| michael@0 | 104 | |
| michael@0 | 105 | /** Call this method when a window's title changes. Listeners (see |
| michael@0 | 106 | * addListener) will be notified through their onWindowTitleChange method. |
| michael@0 | 107 | * @param aWindow the window whose title has changed |
| michael@0 | 108 | * @param inTitle the window's new title |
| michael@0 | 109 | */ |
| michael@0 | 110 | [noscript] void updateWindowTitle(in nsIXULWindow aWindow, |
| michael@0 | 111 | in wstring inTitle ); |
| michael@0 | 112 | |
| michael@0 | 113 | /* z-ordering: */ |
| michael@0 | 114 | |
| michael@0 | 115 | const unsigned long zLevelTop = 1; |
| michael@0 | 116 | const unsigned long zLevelBottom = 2; |
| michael@0 | 117 | const unsigned long zLevelBelow = 3; // below some window |
| michael@0 | 118 | |
| michael@0 | 119 | /** A window wants to be moved in z-order. Calculate whether and how |
| michael@0 | 120 | * it should be constrained. Note this method is advisory only: |
| michael@0 | 121 | * it changes nothing either in WindowMediator's internal state |
| michael@0 | 122 | * or with the window. |
| michael@0 | 123 | * Note it compares the nsIXULWindow to nsIWidgets. A pure interface |
| michael@0 | 124 | * would use all nsIXULWindows. But we expect this to be called from |
| michael@0 | 125 | * callbacks originating in native window code. They are expected to |
| michael@0 | 126 | * hand us comparison values which are pulled from general storage |
| michael@0 | 127 | * in the native widget, and may not correspond to an nsIWidget at all. |
| michael@0 | 128 | * For that reason this interface requires only objects one step |
| michael@0 | 129 | * removed from the native window (nsIWidgets), and its implementation |
| michael@0 | 130 | * must be very understanding of what may be completely invalid |
| michael@0 | 131 | * pointers in those parameters. |
| michael@0 | 132 | * |
| michael@0 | 133 | * @param inWindow the window in question |
| michael@0 | 134 | * @param inPosition requested position |
| michael@0 | 135 | * values: zLevelTop: topmost window. zLevelBottom: bottom. |
| michael@0 | 136 | * zLevelBelow: below ioBelow. (the value of ioBelow will |
| michael@0 | 137 | * be ignored for zLevelTop and Bottom.) |
| michael@0 | 138 | * @param inBelow if inPosition==zLevelBelow, the window |
| michael@0 | 139 | * below which inWindow wants to be placed. Otherwise this |
| michael@0 | 140 | * variable is ignored. |
| michael@0 | 141 | * @param outPosition constrained position, values like inPosition. |
| michael@0 | 142 | * @param outBelow if outPosition==zLevelBelow, the window |
| michael@0 | 143 | * below which inWindow should be placed. Otherwise this |
| michael@0 | 144 | * this value will be null. |
| michael@0 | 145 | * @return PR_TRUE if the position returned is different from |
| michael@0 | 146 | * the position given. |
| michael@0 | 147 | */ |
| michael@0 | 148 | |
| michael@0 | 149 | [noscript] boolean calculateZPosition(in nsIXULWindow inWindow, |
| michael@0 | 150 | in unsigned long inPosition, |
| michael@0 | 151 | in nsIWidget inBelow, |
| michael@0 | 152 | out unsigned long outPosition, |
| michael@0 | 153 | out nsIWidget outBelow); |
| michael@0 | 154 | |
| michael@0 | 155 | /** A window has been positioned behind another. Inform WindowMediator |
| michael@0 | 156 | * @param inWindow the window in question |
| michael@0 | 157 | * @param inPosition new position. values: |
| michael@0 | 158 | * zLevelTop: topmost window. |
| michael@0 | 159 | * zLevelBottom: bottom. |
| michael@0 | 160 | * zLevelBelow: below inBelow. (inBelow is ignored |
| michael@0 | 161 | * for other values of inPosition.) |
| michael@0 | 162 | * @param inBelow the window inWindow is behind, if zLevelBelow |
| michael@0 | 163 | */ |
| michael@0 | 164 | [noscript] void setZPosition(in nsIXULWindow inWindow, |
| michael@0 | 165 | in unsigned long inPosition, |
| michael@0 | 166 | in nsIXULWindow inBelow); |
| michael@0 | 167 | |
| michael@0 | 168 | /** Return the window's Z level (as defined in nsIXULWindow). |
| michael@0 | 169 | * @param aWindow the window in question |
| michael@0 | 170 | * @return aWindow's z level |
| michael@0 | 171 | */ |
| michael@0 | 172 | [noscript] uint32_t getZLevel(in nsIXULWindow aWindow); |
| michael@0 | 173 | |
| michael@0 | 174 | /** Set the window's Z level (as defined in nsIXULWindow). The implementation |
| michael@0 | 175 | * will reposition the window as necessary to match its new Z level. |
| michael@0 | 176 | * The implementation will assume a window's Z level to be |
| michael@0 | 177 | * nsIXULWindow::normalZ until it has been informed of a different level. |
| michael@0 | 178 | * @param aWindow the window in question |
| michael@0 | 179 | * @param aZLevel the window's new Z level |
| michael@0 | 180 | */ |
| michael@0 | 181 | [noscript] void setZLevel(in nsIXULWindow aWindow, in uint32_t aZLevel); |
| michael@0 | 182 | |
| michael@0 | 183 | /** Register a listener for window status changes. |
| michael@0 | 184 | * keeps strong ref? (to be decided) |
| michael@0 | 185 | * @param aListener the listener to register |
| michael@0 | 186 | */ |
| michael@0 | 187 | void addListener(in nsIWindowMediatorListener aListener); |
| michael@0 | 188 | |
| michael@0 | 189 | /** Unregister a listener of window status changes. |
| michael@0 | 190 | * @param aListener the listener to unregister |
| michael@0 | 191 | */ |
| michael@0 | 192 | void removeListener(in nsIWindowMediatorListener aListener); |
| michael@0 | 193 | }; |
