LCOV - code coverage report
Current view: directory - objdir/dist/include - nsIWidget.h (source / functions) Found Hit Coverage
Test: app.info Lines: 43 0 0.0 %
Date: 2012-06-02 Functions: 27 0 0.0 %

       1                 : /* -*- Mode: C++; tab-width: 40; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
       2                 : /* ***** BEGIN LICENSE BLOCK *****
       3                 :  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
       4                 :  *
       5                 :  * The contents of this file are subject to the Mozilla Public License Version
       6                 :  * 1.1 (the "License"); you may not use this file except in compliance with
       7                 :  * the License. You may obtain a copy of the License at
       8                 :  * http://www.mozilla.org/MPL/
       9                 :  *
      10                 :  * Software distributed under the License is distributed on an "AS IS" basis,
      11                 :  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
      12                 :  * for the specific language governing rights and limitations under the
      13                 :  * License.
      14                 :  *
      15                 :  * The Original Code is mozilla.org code.
      16                 :  *
      17                 :  * The Initial Developer of the Original Code is
      18                 :  * Netscape Communications Corporation.
      19                 :  * Portions created by the Initial Developer are Copyright (C) 1998
      20                 :  * the Initial Developer. All Rights Reserved.
      21                 :  *
      22                 :  * Contributor(s):
      23                 :  *
      24                 :  * Alternatively, the contents of this file may be used under the terms of
      25                 :  * either the GNU General Public License Version 2 or later (the "GPL"), or
      26                 :  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
      27                 :  * in which case the provisions of the GPL or the LGPL are applicable instead
      28                 :  * of those above. If you wish to allow use of your version of this file only
      29                 :  * under the terms of either the GPL or the LGPL, and not to allow others to
      30                 :  * use your version of this file under the terms of the MPL, indicate your
      31                 :  * decision by deleting the provisions above and replace them with the notice
      32                 :  * and other provisions required by the GPL or the LGPL. If you do not delete
      33                 :  * the provisions above, a recipient may use your version of this file under
      34                 :  * the terms of any one of the MPL, the GPL or the LGPL.
      35                 :  *
      36                 :  * ***** END LICENSE BLOCK ***** */
      37                 : 
      38                 : #ifndef nsIWidget_h__
      39                 : #define nsIWidget_h__
      40                 : 
      41                 : #include "nsISupports.h"
      42                 : #include "nsColor.h"
      43                 : #include "nsCoord.h"
      44                 : #include "nsRect.h"
      45                 : #include "nsPoint.h"
      46                 : #include "nsRegion.h"
      47                 : #include "nsStringGlue.h"
      48                 : 
      49                 : #include "prthread.h"
      50                 : #include "Layers.h"
      51                 : #include "nsEvent.h"
      52                 : #include "nsCOMPtr.h"
      53                 : #include "nsITheme.h"
      54                 : #include "nsNativeWidget.h"
      55                 : #include "nsWidgetInitData.h"
      56                 : #include "nsTArray.h"
      57                 : #include "nsXULAppAPI.h"
      58                 : 
      59                 : // forward declarations
      60                 : class   nsFontMetrics;
      61                 : class   nsRenderingContext;
      62                 : class   nsDeviceContext;
      63                 : struct  nsFont;
      64                 : class   nsIRollupListener;
      65                 : class   nsGUIEvent;
      66                 : class   imgIContainer;
      67                 : class   gfxASurface;
      68                 : class   nsIContent;
      69                 : class   ViewWrapper;
      70                 : 
      71                 : namespace mozilla {
      72                 : namespace dom {
      73                 : class PBrowserChild;
      74                 : }
      75                 : namespace layers {
      76                 : class PLayersChild;
      77                 : }
      78                 : }
      79                 : 
      80                 : /**
      81                 :  * Callback function that processes events.
      82                 :  *
      83                 :  * The argument is actually a subtype (subclass) of nsEvent which carries
      84                 :  * platform specific information about the event. Platform specific code
      85                 :  * knows how to deal with it.
      86                 :  *
      87                 :  * The return value determines whether or not the default action should take
      88                 :  * place.
      89                 :  */
      90                 : typedef nsEventStatus (* EVENT_CALLBACK)(nsGUIEvent *event);
      91                 : 
      92                 : /**
      93                 :  * Flags for the getNativeData function.
      94                 :  * See getNativeData()
      95                 :  */
      96                 : #define NS_NATIVE_WINDOW      0
      97                 : #define NS_NATIVE_GRAPHIC     1
      98                 : #define NS_NATIVE_TMP_WINDOW  2
      99                 : #define NS_NATIVE_WIDGET      3
     100                 : #define NS_NATIVE_DISPLAY     4
     101                 : #define NS_NATIVE_REGION      5
     102                 : #define NS_NATIVE_OFFSETX     6
     103                 : #define NS_NATIVE_OFFSETY     7
     104                 : #define NS_NATIVE_PLUGIN_PORT 8
     105                 : #define NS_NATIVE_SCREEN      9
     106                 : #define NS_NATIVE_SHELLWIDGET 10      // Get the shell GtkWidget
     107                 : // Has to match to NPNVnetscapeWindow, and shareable across processes
     108                 : // HWND on Windows and XID on X11
     109                 : #define NS_NATIVE_SHAREABLE_WINDOW 11
     110                 : #ifdef XP_MACOSX
     111                 : #define NS_NATIVE_PLUGIN_PORT_QD    100
     112                 : #define NS_NATIVE_PLUGIN_PORT_CG    101
     113                 : #endif
     114                 : #ifdef XP_WIN
     115                 : #define NS_NATIVE_TSF_THREAD_MGR       100
     116                 : #define NS_NATIVE_TSF_CATEGORY_MGR     101
     117                 : #define NS_NATIVE_TSF_DISPLAY_ATTR_MGR 102
     118                 : #endif
     119                 : 
     120                 : #define NS_IWIDGET_IID \
     121                 :   { 0x3fa36ce2, 0x472d, 0x4bff, \
     122                 :     { 0xb1, 0xe4, 0xc3, 0xe3, 0x19, 0x24, 0xa1, 0xe4 } }
     123                 : 
     124                 : /*
     125                 :  * Window shadow styles
     126                 :  * Also used for the -moz-window-shadow CSS property
     127                 :  */
     128                 : 
     129                 : #define NS_STYLE_WINDOW_SHADOW_NONE             0
     130                 : #define NS_STYLE_WINDOW_SHADOW_DEFAULT          1
     131                 : #define NS_STYLE_WINDOW_SHADOW_MENU             2
     132                 : #define NS_STYLE_WINDOW_SHADOW_TOOLTIP          3
     133                 : #define NS_STYLE_WINDOW_SHADOW_SHEET            4
     134                 : 
     135                 : /**
     136                 :  * nsIWidget::OnIMEFocusChange should be called during blur,
     137                 :  * but other OnIME*Change methods should not be called
     138                 :  */
     139                 : #define NS_SUCCESS_IME_NO_UPDATES \
     140                 :     NS_ERROR_GENERATE_SUCCESS(NS_ERROR_MODULE_WIDGET, 1)
     141                 : 
     142                 : /**
     143                 :  * Cursor types.
     144                 :  */
     145                 : 
     146                 : enum nsCursor {   ///(normal cursor,       usually rendered as an arrow)
     147                 :                 eCursor_standard, 
     148                 :                   ///(system is busy,      usually rendered as a hourglass or watch)
     149                 :                 eCursor_wait, 
     150                 :                   ///(Selecting something, usually rendered as an IBeam)
     151                 :                 eCursor_select, 
     152                 :                   ///(can hyper-link,      usually rendered as a human hand)
     153                 :                 eCursor_hyperlink, 
     154                 :                   ///(north/south/west/east edge sizing)
     155                 :                 eCursor_n_resize,
     156                 :                 eCursor_s_resize,
     157                 :                 eCursor_w_resize,
     158                 :                 eCursor_e_resize,
     159                 :                   ///(corner sizing)
     160                 :                 eCursor_nw_resize,
     161                 :                 eCursor_se_resize,
     162                 :                 eCursor_ne_resize,
     163                 :                 eCursor_sw_resize,
     164                 :                 eCursor_crosshair,
     165                 :                 eCursor_move,
     166                 :                 eCursor_help,
     167                 :                 eCursor_copy, // CSS3
     168                 :                 eCursor_alias,
     169                 :                 eCursor_context_menu,
     170                 :                 eCursor_cell,
     171                 :                 eCursor_grab,
     172                 :                 eCursor_grabbing,
     173                 :                 eCursor_spinning,
     174                 :                 eCursor_zoom_in,
     175                 :                 eCursor_zoom_out,
     176                 :                 eCursor_not_allowed,
     177                 :                 eCursor_col_resize,
     178                 :                 eCursor_row_resize,
     179                 :                 eCursor_no_drop,
     180                 :                 eCursor_vertical_text,
     181                 :                 eCursor_all_scroll,
     182                 :                 eCursor_nesw_resize,
     183                 :                 eCursor_nwse_resize,
     184                 :                 eCursor_ns_resize,
     185                 :                 eCursor_ew_resize,
     186                 :                 eCursor_none,
     187                 :                 // This one better be the last one in this list.
     188                 :                 eCursorCount
     189                 :                 }; 
     190                 : 
     191                 : enum nsTopLevelWidgetZPlacement { // for PlaceBehind()
     192                 :   eZPlacementBottom = 0,  // bottom of the window stack
     193                 :   eZPlacementBelow,       // just below another widget
     194                 :   eZPlacementTop          // top of the window stack
     195                 : };
     196                 : 
     197                 : 
     198                 : /**
     199                 :  * Preference for receiving IME updates
     200                 :  *
     201                 :  * If mWantUpdates is true, PuppetWidget will forward
     202                 :  * nsIWidget::OnIMETextChange and nsIWidget::OnIMESelectionChange to the chrome
     203                 :  * process. This incurs overhead from observers and IPDL. If the IME
     204                 :  * implementation on a particular platform doesn't care about OnIMETextChange
     205                 :  * and OnIMESelectionChange from content processes, they should set
     206                 :  * mWantUpdates to false to avoid these overheads.
     207                 :  *
     208                 :  * If mWantHints is true, PuppetWidget will forward the content of text fields
     209                 :  * to the chrome process to be cached. This way we return the cached content
     210                 :  * during query events. (see comments in bug 583976). This only makes sense
     211                 :  * for IME implementations that do use query events, otherwise there's a
     212                 :  * significant overhead. Platforms that don't use query events should set
     213                 :  * mWantHints to false.
     214                 :  */
     215                 : struct nsIMEUpdatePreference {
     216                 : 
     217               0 :   nsIMEUpdatePreference()
     218               0 :     : mWantUpdates(false), mWantHints(false)
     219                 :   {
     220               0 :   }
     221               0 :   nsIMEUpdatePreference(bool aWantUpdates, bool aWantHints)
     222               0 :     : mWantUpdates(aWantUpdates), mWantHints(aWantHints)
     223                 :   {
     224               0 :   }
     225                 :   bool mWantUpdates;
     226                 :   bool mWantHints;
     227                 : };
     228                 : 
     229                 : 
     230                 : /* 
     231                 :  * Contains IMEStatus plus information about the current 
     232                 :  * input context that the IME can use as hints if desired.
     233                 :  */
     234                 : 
     235                 : namespace mozilla {
     236                 : namespace widget {
     237                 : 
     238                 : struct IMEState {
     239                 :   /**
     240                 :    * IME enabled states, the mEnabled value of
     241                 :    * SetInputContext()/GetInputContext() should be one value of following
     242                 :    * values.
     243                 :    *
     244                 :    * WARNING: If you change these values, you also need to edit:
     245                 :    *   nsIDOMWindowUtils.idl
     246                 :    *   nsContentUtils::GetWidgetStatusFromIMEStatus
     247                 :    */
     248                 :   enum Enabled {
     249                 :     /**
     250                 :      * 'Disabled' means the user cannot use IME. So, the IME open state should
     251                 :      * be 'closed' during 'disabled'.
     252                 :      */
     253                 :     DISABLED,
     254                 :     /**
     255                 :      * 'Enabled' means the user can use IME.
     256                 :      */
     257                 :     ENABLED,
     258                 :     /**
     259                 :      * 'Password' state is a special case for the password editors.
     260                 :      * E.g., on mac, the password editors should disable the non-Roman
     261                 :      * keyboard layouts at getting focus. Thus, the password editor may have
     262                 :      * special rules on some platforms.
     263                 :      */
     264                 :     PASSWORD,
     265                 :     /**
     266                 :      * This state is used when a plugin is focused.
     267                 :      * When a plug-in is focused content, we should send native events
     268                 :      * directly. Because we don't process some native events, but they may
     269                 :      * be needed by the plug-in.
     270                 :      */
     271                 :     PLUGIN
     272                 :   };
     273                 :   Enabled mEnabled;
     274                 : 
     275                 :   /**
     276                 :    * IME open states the mOpen value of SetInputContext() should be one value of
     277                 :    * OPEN, CLOSE or DONT_CHANGE_OPEN_STATE.  GetInputContext() should return
     278                 :    * OPEN, CLOSE or OPEN_STATE_NOT_SUPPORTED.
     279                 :    */
     280                 :   enum Open {
     281                 :     /**
     282                 :      * 'Unsupported' means the platform cannot return actual IME open state.
     283                 :      * This value is used only by GetInputContext().
     284                 :      */
     285                 :     OPEN_STATE_NOT_SUPPORTED,
     286                 :     /**
     287                 :      * 'Don't change' means the widget shouldn't change IME open state when
     288                 :      * SetInputContext() is called.
     289                 :      */
     290                 :     DONT_CHANGE_OPEN_STATE = OPEN_STATE_NOT_SUPPORTED,
     291                 :     /**
     292                 :      * 'Open' means that IME should compose in its primary language (or latest
     293                 :      * input mode except direct ASCII character input mode).  Even if IME is
     294                 :      * opened by this value, users should be able to close IME by theirselves.
     295                 :      * Web contents can specify this value by |ime-mode: active;|.
     296                 :      */
     297                 :     OPEN,
     298                 :     /**
     299                 :      * 'Closed' means that IME shouldn't handle key events (or should handle
     300                 :      * as ASCII character inputs on mobile device).  Even if IME is closed by
     301                 :      * this value, users should be able to open IME by theirselves.
     302                 :      * Web contents can specify this value by |ime-mode: inactive;|.
     303                 :      */
     304                 :     CLOSED
     305                 :   };
     306                 :   Open mOpen;
     307                 : 
     308               0 :   IMEState() : mEnabled(ENABLED), mOpen(DONT_CHANGE_OPEN_STATE) { }
     309                 : 
     310               0 :   IMEState(Enabled aEnabled, Open aOpen = DONT_CHANGE_OPEN_STATE) :
     311               0 :     mEnabled(aEnabled), mOpen(aOpen)
     312                 :   {
     313               0 :   }
     314                 : };
     315                 : 
     316               0 : struct InputContext {
     317                 :   IMEState mIMEState;
     318                 : 
     319                 :   /* The type of the input if the input is a html input field */
     320                 :   nsString mHTMLInputType;
     321                 : 
     322                 :   /* A hint for the action that is performed when the input is submitted */
     323                 :   nsString mActionHint;
     324                 : };
     325                 : 
     326                 : struct InputContextAction {
     327                 :   /**
     328                 :    * mCause indicates what action causes calling nsIWidget::SetInputContext().
     329                 :    * It must be one of following values.
     330                 :    */
     331                 :   enum Cause {
     332                 :     // The cause is unknown but originated from content. Focus might have been
     333                 :     // changed by content script.
     334                 :     CAUSE_UNKNOWN,
     335                 :     // The cause is unknown but originated from chrome. Focus might have been
     336                 :     // changed by chrome script.
     337                 :     CAUSE_UNKNOWN_CHROME,
     338                 :     // The cause is user's keyboard operation.
     339                 :     CAUSE_KEY,
     340                 :     // The cause is user's mouse operation.
     341                 :     CAUSE_MOUSE
     342                 :   };
     343                 :   Cause mCause;
     344                 : 
     345                 :   /**
     346                 :    * mFocusChange indicates what happened for focus.
     347                 :    */
     348                 :   enum FocusChange {
     349                 :     FOCUS_NOT_CHANGED,
     350                 :     // A content got focus.
     351                 :     GOT_FOCUS,
     352                 :     // Focused content lost focus.
     353                 :     LOST_FOCUS,
     354                 :     // Menu got pseudo focus that means focused content isn't changed but
     355                 :     // keyboard events will be handled by menu.
     356                 :     MENU_GOT_PSEUDO_FOCUS,
     357                 :     // Menu lost pseudo focus that means focused content will handle keyboard
     358                 :     // events.
     359                 :     MENU_LOST_PSEUDO_FOCUS
     360                 :   };
     361                 :   FocusChange mFocusChange;
     362                 : 
     363                 :   bool ContentGotFocusByTrustedCause() const {
     364                 :     return (mFocusChange == GOT_FOCUS &&
     365                 :             mCause != CAUSE_UNKNOWN);
     366                 :   }
     367                 : 
     368                 :   bool UserMightRequestOpenVKB() const {
     369                 :     return (mFocusChange == FOCUS_NOT_CHANGED &&
     370                 :             mCause == CAUSE_MOUSE);
     371                 :   }
     372                 : 
     373                 :   InputContextAction() :
     374                 :     mCause(CAUSE_UNKNOWN), mFocusChange(FOCUS_NOT_CHANGED)
     375                 :   {
     376                 :   }
     377                 : 
     378               0 :   InputContextAction(Cause aCause,
     379                 :                      FocusChange aFocusChange = FOCUS_NOT_CHANGED) :
     380               0 :     mCause(aCause), mFocusChange(aFocusChange)
     381                 :   {
     382               0 :   }
     383                 : };
     384                 : 
     385                 : } // namespace widget
     386                 : } // namespace mozilla
     387                 : 
     388                 : /**
     389                 :  * The base class for all the widgets. It provides the interface for
     390                 :  * all basic and necessary functionality.
     391                 :  */
     392               0 : class nsIWidget : public nsISupports {
     393                 :   protected:
     394                 :     typedef mozilla::dom::PBrowserChild PBrowserChild;
     395                 : 
     396                 :   public:
     397                 :     typedef mozilla::layers::LayerManager LayerManager;
     398                 :     typedef LayerManager::LayersBackend LayersBackend;
     399                 :     typedef mozilla::layers::PLayersChild PLayersChild;
     400                 :     typedef mozilla::widget::IMEState IMEState;
     401                 :     typedef mozilla::widget::InputContext InputContext;
     402                 :     typedef mozilla::widget::InputContextAction InputContextAction;
     403                 : 
     404                 :     // Used in UpdateThemeGeometries.
     405               0 :     struct ThemeGeometry {
     406                 :       // The -moz-appearance value for the themed widget
     407                 :       PRUint8 mWidgetType;
     408                 :       // The device-pixel rect within the window for the themed widget
     409                 :       nsIntRect mRect;
     410                 : 
     411               0 :       ThemeGeometry(PRUint8 aWidgetType, const nsIntRect& aRect)
     412                 :        : mWidgetType(aWidgetType)
     413               0 :        , mRect(aRect)
     414               0 :       { }
     415                 :     };
     416                 : 
     417                 :     NS_DECLARE_STATIC_IID_ACCESSOR(NS_IWIDGET_IID)
     418                 : 
     419               0 :     nsIWidget()
     420                 :       : mLastChild(nsnull)
     421               0 :       , mPrevSibling(nsnull)
     422               0 :     {}
     423                 : 
     424                 :         
     425                 :     /**
     426                 :      * Create and initialize a widget. 
     427                 :      *
     428                 :      * All the arguments can be NULL in which case a top level window
     429                 :      * with size 0 is created. The event callback function has to be
     430                 :      * provided only if the caller wants to deal with the events this
     431                 :      * widget receives.  The event callback is basically a preprocess
     432                 :      * hook called synchronously. The return value determines whether
     433                 :      * the event goes to the default window procedure or it is hidden
     434                 :      * to the os. The assumption is that if the event handler returns
     435                 :      * false the widget does not see the event. The widget should not 
     436                 :      * automatically clear the window to the background color. The 
     437                 :      * calling code must handle paint messages and clear the background 
     438                 :      * itself. 
     439                 :      *
     440                 :      * In practice at least one of aParent and aNativeParent will be null. If
     441                 :      * both are null the widget isn't parented (e.g. context menus or
     442                 :      * independent top level windows).
     443                 :      *
     444                 :      * @param     aParent       parent nsIWidget
     445                 :      * @param     aNativeParent native parent widget
     446                 :      * @param     aRect         the widget dimension
     447                 :      * @param     aHandleEventFunction the event handler callback function
     448                 :      * @param     aContext
     449                 :      * @param     aInitData     data that is used for widget initialization
     450                 :      *
     451                 :      */
     452                 :     NS_IMETHOD Create(nsIWidget        *aParent,
     453                 :                       nsNativeWidget   aNativeParent,
     454                 :                       const nsIntRect  &aRect,
     455                 :                       EVENT_CALLBACK   aHandleEventFunction,
     456                 :                       nsDeviceContext *aContext,
     457                 :                       nsWidgetInitData *aInitData = nsnull) = 0;
     458                 : 
     459                 :     /**
     460                 :      * Allocate, initialize, and return a widget that is a child of
     461                 :      * |this|.  The returned widget (if nonnull) has gone through the
     462                 :      * equivalent of CreateInstance(widgetCID) + Create(...).
     463                 :      *
     464                 :      * |CreateChild()| lets widget backends decide whether to parent
     465                 :      * the new child widget to this, nonnatively parent it, or both.
     466                 :      * This interface exists to support the PuppetWidget backend,
     467                 :      * which is entirely non-native.  All other params are the same as
     468                 :      * for |Create()|.
     469                 :      *
     470                 :      * |aForceUseIWidgetParent| forces |CreateChild()| to only use the
     471                 :      * |nsIWidget*| this, not its native widget (if it exists), when
     472                 :      * calling |Create()|.  This is a timid hack around poorly
     473                 :      * understood code, and shouldn't be used in new code.
     474                 :      */
     475                 :     virtual already_AddRefed<nsIWidget>
     476                 :     CreateChild(const nsIntRect  &aRect,
     477                 :                 EVENT_CALLBACK   aHandleEventFunction,
     478                 :                 nsDeviceContext  *aContext,
     479                 :                 nsWidgetInitData *aInitData = nsnull,
     480                 :                 bool             aForceUseIWidgetParent = false) = 0;
     481                 : 
     482                 :     /**
     483                 :      * Set the event callback for a widget. If a device context is not
     484                 :      * provided then the existing device context will remain, it will
     485                 :      * not be nulled out.
     486                 :      */
     487                 :     NS_IMETHOD SetEventCallback(EVENT_CALLBACK aEventFunction,
     488                 :                                 nsDeviceContext *aContext) = 0;
     489                 : 
     490                 :     /**
     491                 :      * Attach to a top level widget. 
     492                 :      *
     493                 :      * In cases where a top level chrome widget is being used as a content
     494                 :      * container, attach a secondary event callback and update the device
     495                 :      * context. The primary event callback will continue to be called, so the
     496                 :      * owning base window will continue to function.
     497                 :      *
     498                 :      * aViewEventFunction Event callback that will receive mirrored
     499                 :      *                    events.
     500                 :      * aContext The new device context for the view
     501                 :      */
     502                 :     NS_IMETHOD AttachViewToTopLevel(EVENT_CALLBACK aViewEventFunction,
     503                 :                                     nsDeviceContext *aContext) = 0;
     504                 : 
     505                 :     /**
     506                 :      * Accessor functions to get and set secondary client data. Used by
     507                 :      * nsIView in connection with AttachViewToTopLevel above.
     508                 :      */
     509                 :     NS_IMETHOD SetAttachedViewPtr(ViewWrapper* aViewWrapper) = 0;
     510                 :     virtual ViewWrapper* GetAttachedViewPtr() = 0;
     511                 : 
     512                 :     /**
     513                 :      * Accessor functions to get and set the client data associated with the
     514                 :      * widget.
     515                 :      */
     516                 :     //@{
     517                 :     NS_IMETHOD  GetClientData(void*& aClientData) = 0;
     518                 :     NS_IMETHOD  SetClientData(void* aClientData) = 0;
     519                 :     //@}
     520                 : 
     521                 :     /**
     522                 :      * Close and destroy the internal native window. 
     523                 :      * This method does not delete the widget.
     524                 :      */
     525                 : 
     526                 :     NS_IMETHOD Destroy(void) = 0;
     527                 : 
     528                 : 
     529                 :     /**
     530                 :      * Reparent a widget
     531                 :      *
     532                 :      * Change the widget's parent. Null parents are allowed.
     533                 :      *
     534                 :      * @param     aNewParent   new parent 
     535                 :      */
     536                 :     NS_IMETHOD SetParent(nsIWidget* aNewParent) = 0;
     537                 : 
     538                 :     NS_IMETHOD RegisterTouchWindow() = 0;
     539                 :     NS_IMETHOD UnregisterTouchWindow() = 0;
     540                 : 
     541                 :     /**
     542                 :      * Return the parent Widget of this Widget or nsnull if this is a 
     543                 :      * top level window
     544                 :      *
     545                 :      * @return the parent widget or nsnull if it does not have a parent
     546                 :      *
     547                 :      */
     548                 :     virtual nsIWidget* GetParent(void) = 0;
     549                 : 
     550                 :     /**
     551                 :      * Return the top level Widget of this Widget
     552                 :      *
     553                 :      * @return the top level widget
     554                 :      */
     555                 :     virtual nsIWidget* GetTopLevelWidget() = 0;
     556                 : 
     557                 :     /**
     558                 :      * Return the top (non-sheet) parent of this Widget if it's a sheet,
     559                 :      * or nsnull if this isn't a sheet (or some other error occurred).
     560                 :      * Sheets are only supported on some platforms (currently only OS X).
     561                 :      *
     562                 :      * @return the top (non-sheet) parent widget or nsnull
     563                 :      *
     564                 :      */
     565                 :     virtual nsIWidget* GetSheetWindowParent(void) = 0;
     566                 : 
     567                 :     /**
     568                 :      * Return the physical DPI of the screen containing the window ...
     569                 :      * the number of device pixels per inch.
     570                 :      */
     571                 :     virtual float GetDPI() = 0;
     572                 : 
     573                 :     /**
     574                 :      * Return the default scale factor for the window. This is the
     575                 :      * default number of device pixels per CSS pixel to use. This should
     576                 :      * depend on OS/platform settings such as the Mac's "UI scale factor"
     577                 :      * or Windows' "font DPI".
     578                 :      */
     579                 :     virtual double GetDefaultScale() = 0;
     580                 : 
     581                 :     /**
     582                 :      * Return the first child of this widget.  Will return null if
     583                 :      * there are no children.
     584                 :      */
     585               0 :     nsIWidget* GetFirstChild() const {
     586               0 :         return mFirstChild;
     587                 :     }
     588                 :     
     589                 :     /**
     590                 :      * Return the last child of this widget.  Will return null if
     591                 :      * there are no children.
     592                 :      */
     593                 :     nsIWidget* GetLastChild() const {
     594                 :         return mLastChild;
     595                 :     }
     596                 : 
     597                 :     /**
     598                 :      * Return the next sibling of this widget
     599                 :      */
     600               0 :     nsIWidget* GetNextSibling() const {
     601               0 :         return mNextSibling;
     602                 :     }
     603                 :     
     604                 :     /**
     605                 :      * Set the next sibling of this widget
     606                 :      */
     607               0 :     void SetNextSibling(nsIWidget* aSibling) {
     608               0 :         mNextSibling = aSibling;
     609               0 :     }
     610                 :     
     611                 :     /**
     612                 :      * Return the previous sibling of this widget
     613                 :      */
     614               0 :     nsIWidget* GetPrevSibling() const {
     615               0 :         return mPrevSibling;
     616                 :     }
     617                 : 
     618                 :     /**
     619                 :      * Set the previous sibling of this widget
     620                 :      */
     621               0 :     void SetPrevSibling(nsIWidget* aSibling) {
     622               0 :         mPrevSibling = aSibling;
     623               0 :     }
     624                 : 
     625                 :     /**
     626                 :      * Show or hide this widget
     627                 :      *
     628                 :      * @param aState true to show the Widget, false to hide it
     629                 :      *
     630                 :      */
     631                 :     NS_IMETHOD Show(bool aState) = 0;
     632                 : 
     633                 :     /**
     634                 :      * Make the window modal
     635                 :      *
     636                 :      */
     637                 :     NS_IMETHOD SetModal(bool aModal) = 0;
     638                 : 
     639                 :     /**
     640                 :      * Returns whether the window is visible
     641                 :      *
     642                 :      */
     643                 :     NS_IMETHOD IsVisible(bool & aState) = 0;
     644                 : 
     645                 :     /**
     646                 :      * Perform platform-dependent sanity check on a potential window position.
     647                 :      * This is guaranteed to work only for top-level windows.
     648                 :      *
     649                 :      * @param aAllowSlop: if true, allow the window to slop offscreen;
     650                 :      *                    the window should be partially visible. if false,
     651                 :      *                    force the entire window onscreen (or at least
     652                 :      *                    the upper-left corner, if it's too large).
     653                 :      * @param aX in: an x position expressed in screen coordinates.
     654                 :      *           out: the x position constrained to fit on the screen(s).
     655                 :      * @param aY in: an y position expressed in screen coordinates.
     656                 :      *           out: the y position constrained to fit on the screen(s).
     657                 :      * @return vapid success indication. but see also the parameters.
     658                 :      *
     659                 :      **/
     660                 :     NS_IMETHOD ConstrainPosition(bool aAllowSlop,
     661                 :                                  PRInt32 *aX,
     662                 :                                  PRInt32 *aY) = 0;
     663                 : 
     664                 :     /**
     665                 :      * Move this widget.
     666                 :      *
     667                 :      * Coordinates refer to the top-left of the widget.  For toplevel windows
     668                 :      * with decorations, this is the top-left of the titlebar and frame .
     669                 :      *
     670                 :      * @param aX the new x position expressed in the parent's coordinate system
     671                 :      * @param aY the new y position expressed in the parent's coordinate system
     672                 :      *
     673                 :      **/
     674                 :     NS_IMETHOD Move(PRInt32 aX, PRInt32 aY) = 0;
     675                 : 
     676                 :     /**
     677                 :      * Reposition this widget so that the client area has the given offset.
     678                 :      *
     679                 :      * @param aX       the new x offset of the client area expressed as an
     680                 :      *                 offset from the origin of the client area of the parent
     681                 :      *                 widget (for root widgets and popup widgets it is in
     682                 :      *                 screen coordinates)
     683                 :      * @param aY       the new y offset of the client area expressed as an
     684                 :      *                 offset from the origin of the client area of the parent
     685                 :      *                 widget (for root widgets and popup widgets it is in
     686                 :      *                 screen coordinates)
     687                 :      *
     688                 :      **/
     689                 :     NS_IMETHOD MoveClient(PRInt32 aX, PRInt32 aY) = 0;
     690                 : 
     691                 :     /**
     692                 :      * Resize this widget. 
     693                 :      *
     694                 :      * @param aWidth  the new width expressed in the parent's coordinate system
     695                 :      * @param aHeight the new height expressed in the parent's coordinate system
     696                 :      * @param aRepaint whether the widget should be repainted
     697                 :      *
     698                 :      */
     699                 :     NS_IMETHOD Resize(PRInt32 aWidth,
     700                 :                       PRInt32 aHeight,
     701                 :                       bool     aRepaint) = 0;
     702                 : 
     703                 :     /**
     704                 :      * Move or resize this widget.
     705                 :      *
     706                 :      * @param aX       the new x position expressed in the parent's coordinate system
     707                 :      * @param aY       the new y position expressed in the parent's coordinate system
     708                 :      * @param aWidth   the new width expressed in the parent's coordinate system
     709                 :      * @param aHeight  the new height expressed in the parent's coordinate system
     710                 :      * @param aRepaint whether the widget should be repainted if the size changes
     711                 :      *
     712                 :      */
     713                 :     NS_IMETHOD Resize(PRInt32 aX,
     714                 :                       PRInt32 aY,
     715                 :                       PRInt32 aWidth,
     716                 :                       PRInt32 aHeight,
     717                 :                       bool     aRepaint) = 0;
     718                 : 
     719                 :     /**
     720                 :      * Resize the widget so that the inner client area has the given size.
     721                 :      *
     722                 :      * @param aWidth   the new width of the client area.
     723                 :      * @param aHeight  the new height of the client area.
     724                 :      * @param aRepaint whether the widget should be repainted
     725                 :      *
     726                 :      */
     727                 :     NS_IMETHOD ResizeClient(PRInt32 aWidth,
     728                 :                             PRInt32 aHeight,
     729                 :                             bool  aRepaint) = 0;
     730                 : 
     731                 :     /**
     732                 :      * Resize and reposition the widget so tht inner client area has the given
     733                 :      * offset and size.
     734                 :      *
     735                 :      * @param aX       the new x offset of the client area expressed as an
     736                 :      *                 offset from the origin of the client area of the parent
     737                 :      *                 widget (for root widgets and popup widgets it is in
     738                 :      *                 screen coordinates)
     739                 :      * @param aY       the new y offset of the client area expressed as an
     740                 :      *                 offset from the origin of the client area of the parent
     741                 :      *                 widget (for root widgets and popup widgets it is in
     742                 :      *                 screen coordinates)
     743                 :      * @param aWidth   the new width of the client area.
     744                 :      * @param aHeight  the new height of the client area.
     745                 :      * @param aRepaint whether the widget should be repainted
     746                 :      *
     747                 :      */
     748                 :     NS_IMETHOD ResizeClient(PRInt32 aX,
     749                 :                             PRInt32 aY,
     750                 :                             PRInt32 aWidth,
     751                 :                             PRInt32 aHeight,
     752                 :                             bool    aRepaint) = 0;
     753                 : 
     754                 :     /**
     755                 :      * Sets the widget's z-index.
     756                 :      */
     757                 :     NS_IMETHOD SetZIndex(PRInt32 aZIndex) = 0;
     758                 : 
     759                 :     /**
     760                 :      * Gets the widget's z-index. 
     761                 :      */
     762                 :     NS_IMETHOD GetZIndex(PRInt32* aZIndex) = 0;
     763                 : 
     764                 :     /**
     765                 :      * Position this widget just behind the given widget. (Used to
     766                 :      * control z-order for top-level widgets. Get/SetZIndex by contrast
     767                 :      * control z-order for child widgets of other widgets.)
     768                 :      * @param aPlacement top, bottom, or below a widget
     769                 :      *                   (if top or bottom, param aWidget is ignored)
     770                 :      * @param aWidget    widget to place this widget behind
     771                 :      *                   (only if aPlacement is eZPlacementBelow).
     772                 :      *                   null is equivalent to aPlacement of eZPlacementTop
     773                 :      * @param aActivate  true to activate the widget after placing it
     774                 :      */
     775                 :     NS_IMETHOD PlaceBehind(nsTopLevelWidgetZPlacement aPlacement,
     776                 :                            nsIWidget *aWidget, bool aActivate) = 0;
     777                 : 
     778                 :     /**
     779                 :      * Minimize, maximize or normalize the window size.
     780                 :      * Takes a value from nsSizeMode (see nsGUIEvent.h)
     781                 :      */
     782                 :     NS_IMETHOD SetSizeMode(PRInt32 aMode) = 0;
     783                 : 
     784                 :     /**
     785                 :      * Return size mode (minimized, maximized, normalized).
     786                 :      * Returns a value from nsSizeMode (see nsGUIEvent.h)
     787                 :      */
     788                 :     NS_IMETHOD GetSizeMode(PRInt32* aMode) = 0;
     789                 : 
     790                 :     /**
     791                 :      * Enable or disable this Widget
     792                 :      *
     793                 :      * @param aState true to enable the Widget, false to disable it.
     794                 :      *
     795                 :      */
     796                 :     NS_IMETHOD Enable(bool aState) = 0;
     797                 : 
     798                 :     /**
     799                 :      * Ask whether the widget is enabled
     800                 :      * @param aState returns true if the widget is enabled
     801                 :      */
     802                 :     NS_IMETHOD IsEnabled(bool *aState) = 0;
     803                 : 
     804                 :     /**
     805                 :      * Request activation of this window or give focus to this widget.
     806                 :      *
     807                 :      * @param aRaise If true, this function requests activation of this
     808                 :      *               widget's toplevel window.
     809                 :      *               If false, the appropriate toplevel window (which in
     810                 :      *               the case of popups may not be this widget's toplevel
     811                 :      *               window) is already active, and this function indicates
     812                 :      *               that keyboard events should be reported through the
     813                 :      *               aHandleEventFunction provided to this->Create().
     814                 :      */
     815                 :     NS_IMETHOD SetFocus(bool aRaise = false) = 0;
     816                 : 
     817                 :     /**
     818                 :      * Get this widget's outside dimensions relative to its parent widget. For
     819                 :      * popup widgets the returned rect is in screen coordinates and not
     820                 :      * relative to its parent widget.
     821                 :      *
     822                 :      * @param aRect   On return it holds the  x, y, width and height of
     823                 :      *                this widget.
     824                 :      */
     825                 :     NS_IMETHOD GetBounds(nsIntRect &aRect) = 0;
     826                 : 
     827                 :     /**
     828                 :      * Get this widget's outside dimensions in global coordinates. This
     829                 :      * includes any title bar on the window.
     830                 :      *
     831                 :      * @param aRect   On return it holds the  x, y, width and height of
     832                 :      *                this widget.
     833                 :      */
     834                 :     NS_IMETHOD GetScreenBounds(nsIntRect &aRect) = 0;
     835                 : 
     836                 :     /**
     837                 :      * Get this widget's client area bounds, if the window has a 3D border
     838                 :      * appearance this returns the area inside the border. The position is the
     839                 :      * position of the client area relative to the client area of the parent
     840                 :      * widget (for root widgets and popup widgets it is in screen coordinates).
     841                 :      *
     842                 :      * @param aRect   On return it holds the  x. y, width and height of
     843                 :      *                the client area of this widget.
     844                 :      */
     845                 :     NS_IMETHOD GetClientBounds(nsIntRect &aRect) = 0;
     846                 : 
     847                 :     /**
     848                 :      * Get the non-client area dimensions of the window.
     849                 :      * 
     850                 :      */
     851                 :     NS_IMETHOD GetNonClientMargins(nsIntMargin &margins) = 0;
     852                 : 
     853                 :     /**
     854                 :      * Sets the non-client area dimensions of the window. Pass -1 to restore
     855                 :      * the system default frame size for that border. Pass zero to remove
     856                 :      * a border, or pass a specific value adjust a border. Units are in
     857                 :      * pixels. (DPI dependent)
     858                 :      *
     859                 :      * Platform notes:
     860                 :      *  Windows: shrinking top non-client height will remove application
     861                 :      *  icon and window title text. Glass desktops will refuse to set
     862                 :      *  dimensions between zero and size < system default.
     863                 :      *
     864                 :      */
     865                 :     NS_IMETHOD SetNonClientMargins(nsIntMargin &margins) = 0;
     866                 : 
     867                 :     /**
     868                 :      * Get the client offset from the window origin.
     869                 :      *
     870                 :      * @return the x and y of the offset.
     871                 :      *
     872                 :      */
     873                 :     virtual nsIntPoint GetClientOffset() = 0;
     874                 : 
     875                 :     /**
     876                 :      * Get the foreground color for this widget
     877                 :      *
     878                 :      * @return this widget's foreground color
     879                 :      *
     880                 :      */
     881                 :     virtual nscolor GetForegroundColor(void) = 0;
     882                 : 
     883                 :     /**
     884                 :      * Set the foreground color for this widget
     885                 :      *
     886                 :      * @param aColor the new foreground color
     887                 :      *
     888                 :      */
     889                 : 
     890                 :     NS_IMETHOD SetForegroundColor(const nscolor &aColor) = 0;
     891                 : 
     892                 :     /**
     893                 :      * Get the background color for this widget
     894                 :      *
     895                 :      * @return this widget's background color
     896                 :      *
     897                 :      */
     898                 : 
     899                 :     virtual nscolor GetBackgroundColor(void) = 0;
     900                 : 
     901                 :     /**
     902                 :      * Set the background color for this widget
     903                 :      *
     904                 :      * @param aColor the new background color
     905                 :      *
     906                 :      */
     907                 : 
     908                 :     NS_IMETHOD SetBackgroundColor(const nscolor &aColor) = 0;
     909                 : 
     910                 :     /**
     911                 :      * Get the cursor for this widget.
     912                 :      *
     913                 :      * @return this widget's cursor.
     914                 :      */
     915                 : 
     916                 :     virtual nsCursor GetCursor(void) = 0;
     917                 : 
     918                 :     /**
     919                 :      * Set the cursor for this widget
     920                 :      *
     921                 :      * @param aCursor the new cursor for this widget
     922                 :      */
     923                 : 
     924                 :     NS_IMETHOD SetCursor(nsCursor aCursor) = 0;
     925                 : 
     926                 :     /**
     927                 :      * Sets an image as the cursor for this widget.
     928                 :      *
     929                 :      * @param aCursor the cursor to set
     930                 :      * @param aX the X coordinate of the hotspot (from left).
     931                 :      * @param aY the Y coordinate of the hotspot (from top).
     932                 :      * @retval NS_ERROR_NOT_IMPLEMENTED if setting images as cursors is not
     933                 :      *         supported
     934                 :      */
     935                 :     NS_IMETHOD SetCursor(imgIContainer* aCursor,
     936                 :                          PRUint32 aHotspotX, PRUint32 aHotspotY) = 0;
     937                 : 
     938                 :     /** 
     939                 :      * Get the window type of this widget
     940                 :      *
     941                 :      * @param aWindowType the window type of the widget
     942                 :      */
     943                 :     NS_IMETHOD GetWindowType(nsWindowType& aWindowType) = 0;
     944                 : 
     945                 :     /**
     946                 :      * Set the transparency mode of the top-level window containing this widget.
     947                 :      * So, e.g., if you call this on the widget for an IFRAME, the top level
     948                 :      * browser window containing the IFRAME actually gets set. Be careful.
     949                 :      *
     950                 :      * This can fail if the platform doesn't support
     951                 :      * transparency/glass. By default widgets are not
     952                 :      * transparent.  This will also fail if the toplevel window is not
     953                 :      * a Mozilla window, e.g., if the widget is in an embedded
     954                 :      * context.
     955                 :      *
     956                 :      * After transparency/glass has been enabled, the initial alpha channel
     957                 :      * value for all pixels is 1, i.e., opaque.
     958                 :      * If the window is resized then the alpha channel values for
     959                 :      * all pixels are reset to 1.
     960                 :      * Pixel RGB color values are already premultiplied with alpha channel values.
     961                 :      */
     962                 :     virtual void SetTransparencyMode(nsTransparencyMode aMode) = 0;
     963                 : 
     964                 :     /**
     965                 :      * Get the transparency mode of the top-level window that contains this
     966                 :      * widget.
     967                 :      */
     968                 :     virtual nsTransparencyMode GetTransparencyMode() = 0;
     969                 : 
     970                 :     /**
     971                 :      * This represents a command to set the bounds and clip region of
     972                 :      * a child widget.
     973                 :      */
     974               0 :     struct Configuration {
     975                 :         nsIWidget* mChild;
     976                 :         nsIntRect mBounds;
     977                 :         nsTArray<nsIntRect> mClipRegion;
     978                 :     };
     979                 : 
     980                 :     /**
     981                 :      * Sets the clip region of each mChild (which must actually be a child
     982                 :      * of this widget) to the union of the pixel rects given in
     983                 :      * mClipRegion, all relative to the top-left of the child
     984                 :      * widget. Clip regions are not implemented on all platforms and only
     985                 :      * need to actually work for children that are plugins.
     986                 :      * 
     987                 :      * Also sets the bounds of each child to mBounds.
     988                 :      * 
     989                 :      * This will invalidate areas of the children that have changed, but
     990                 :      * does not need to invalidate any part of this widget.
     991                 :      * 
     992                 :      * Children should be moved in the order given; the array is
     993                 :      * sorted so to minimize unnecessary invalidation if children are
     994                 :      * moved in that order.
     995                 :      */
     996                 :     virtual nsresult ConfigureChildren(const nsTArray<Configuration>& aConfigurations) = 0;
     997                 : 
     998                 :     /**
     999                 :      * Appends to aRects the rectangles constituting this widget's clip
    1000                 :      * region. If this widget is not clipped, appends a single rectangle
    1001                 :      * (0, 0, bounds.width, bounds.height).
    1002                 :      */
    1003                 :     virtual void GetWindowClipRegion(nsTArray<nsIntRect>* aRects) = 0;
    1004                 : 
    1005                 :     /**
    1006                 :      * Set the shadow style of the window.
    1007                 :      *
    1008                 :      * Ignored on child widgets and on non-Mac platforms.
    1009                 :      */
    1010                 :     NS_IMETHOD SetWindowShadowStyle(PRInt32 aStyle) = 0;
    1011                 : 
    1012                 :     /*
    1013                 :      * On Mac OS X, this method shows or hides the pill button in the titlebar
    1014                 :      * that's used to collapse the toolbar.
    1015                 :      *
    1016                 :      * Ignored on child widgets and on non-Mac platforms.
    1017                 :      */
    1018                 :     virtual void SetShowsToolbarButton(bool aShow) = 0;
    1019                 : 
    1020                 :     enum WindowAnimationType {
    1021                 :       eGenericWindowAnimation,
    1022                 :       eDocumentWindowAnimation
    1023                 :     };
    1024                 : 
    1025                 :     /**
    1026                 :      * Sets the kind of top-level window animation this widget should have.  On
    1027                 :      * Mac OS X, this causes a particular kind of animation to be shown when the
    1028                 :      * window is first made visible.
    1029                 :      *
    1030                 :      * Ignored on child widgets and on non-Mac platforms.
    1031                 :      */
    1032                 :     virtual void SetWindowAnimationType(WindowAnimationType aType) = 0;
    1033                 : 
    1034                 :     /** 
    1035                 :      * Hide window chrome (borders, buttons) for this widget.
    1036                 :      *
    1037                 :      */
    1038                 :     NS_IMETHOD HideWindowChrome(bool aShouldHide) = 0;
    1039                 : 
    1040                 :     /**
    1041                 :      * Put the toplevel window into or out of fullscreen mode.
    1042                 :      *
    1043                 :      */
    1044                 :     NS_IMETHOD MakeFullScreen(bool aFullScreen) = 0;
    1045                 : 
    1046                 :     /**
    1047                 :      * Invalidate a specified rect for a widget so that it will be repainted
    1048                 :      * later.
    1049                 :      */
    1050                 :     NS_IMETHOD Invalidate(const nsIntRect & aRect) = 0;
    1051                 : 
    1052                 :     enum LayerManagerPersistence
    1053                 :     {
    1054                 :       LAYER_MANAGER_CURRENT = 0,
    1055                 :       LAYER_MANAGER_PERSISTENT
    1056                 :     };
    1057                 : 
    1058                 :     /**
    1059                 :      * Return the widget's LayerManager. The layer tree for that
    1060                 :      * LayerManager is what gets rendered to the widget.
    1061                 :      *
    1062                 :      * @param aAllowRetaining an outparam that states whether the returned
    1063                 :      * layer manager should be used for retained layers
    1064                 :      */
    1065               0 :     inline LayerManager* GetLayerManager(bool* aAllowRetaining = nsnull)
    1066                 :     {
    1067                 :         return GetLayerManager(nsnull, LayerManager::LAYERS_NONE,
    1068               0 :                                LAYER_MANAGER_CURRENT, aAllowRetaining);
    1069                 :     }
    1070                 : 
    1071               0 :     inline LayerManager* GetLayerManager(LayerManagerPersistence aPersistence,
    1072                 :                                          bool* aAllowRetaining = nsnull)
    1073                 :     {
    1074                 :         return GetLayerManager(nsnull, LayerManager::LAYERS_NONE,
    1075               0 :                                aPersistence, aAllowRetaining);
    1076                 :     }
    1077                 : 
    1078                 :     /**
    1079                 :      * Like GetLayerManager(), but prefers creating a layer manager of
    1080                 :      * type |aBackendHint| instead of what would normally be created.
    1081                 :      * LAYERS_NONE means "no hint".
    1082                 :      */
    1083                 :     virtual LayerManager* GetLayerManager(PLayersChild* aShadowManager,
    1084                 :                                           LayersBackend aBackendHint,
    1085                 :                                           LayerManagerPersistence aPersistence = LAYER_MANAGER_CURRENT,
    1086                 :                                           bool* aAllowRetaining = nsnull) = 0;
    1087                 : 
    1088                 :     /**
    1089                 :      * Called after the LayerManager draws the layer tree
    1090                 :      *
    1091                 :      * @param aManager The drawing LayerManager.
    1092                 :      * @param aRect Current widget rect that is being drawn.
    1093                 :      */
    1094                 :     virtual void DrawWindowOverlay(LayerManager* aManager, nsIntRect aRect) = 0;
    1095                 : 
    1096                 :     /**
    1097                 :      * Called when Gecko knows which themed widgets exist in this window.
    1098                 :      * The passed array contains an entry for every themed widget of the right
    1099                 :      * type (currently only NS_THEME_MOZ_MAC_UNIFIED_TOOLBAR and
    1100                 :      * NS_THEME_TOOLBAR) within the window, except for themed widgets which are
    1101                 :      * transformed or have effects applied to them (e.g. CSS opacity or
    1102                 :      * filters).
    1103                 :      * This could sometimes be called during display list construction
    1104                 :      * outside of painting.
    1105                 :      * If called during painting, it will be called before we actually
    1106                 :      * paint anything.
    1107                 :      */
    1108                 :     virtual void UpdateThemeGeometries(const nsTArray<ThemeGeometry>& aThemeGeometries) = 0;
    1109                 : 
    1110                 :     /**
    1111                 :      * Informs the widget about the region of the window that is opaque.
    1112                 :      *
    1113                 :      * @param aOpaqueRegion the region of the window that is opaque.
    1114                 :      */
    1115               0 :     virtual void UpdateOpaqueRegion(const nsIntRegion &aOpaqueRegion) {};
    1116                 : 
    1117                 :     /** 
    1118                 :      * Internal methods
    1119                 :      */
    1120                 : 
    1121                 :     //@{
    1122                 :     virtual void AddChild(nsIWidget* aChild) = 0;
    1123                 :     virtual void RemoveChild(nsIWidget* aChild) = 0;
    1124                 :     virtual void* GetNativeData(PRUint32 aDataType) = 0;
    1125                 :     virtual void FreeNativeData(void * data, PRUint32 aDataType) = 0;//~~~
    1126                 : 
    1127                 :     // GetDeviceContext returns a weak pointer to this widget's device context
    1128                 :     virtual nsDeviceContext* GetDeviceContext() = 0;
    1129                 : 
    1130                 :     //@}
    1131                 : 
    1132                 :     /**
    1133                 :      * Set the widget's title.
    1134                 :      * Must be called after Create.
    1135                 :      *
    1136                 :      * @param aTitle string displayed as the title of the widget
    1137                 :      */
    1138                 : 
    1139                 :     NS_IMETHOD SetTitle(const nsAString& aTitle) = 0;
    1140                 : 
    1141                 :     /**
    1142                 :      * Set the widget's icon.
    1143                 :      * Must be called after Create.
    1144                 :      *
    1145                 :      * @param anIconSpec string specifying the icon to use; convention is to pass
    1146                 :      *                   a resource: URL from which a platform-dependent resource
    1147                 :      *                   file name will be constructed
    1148                 :      */
    1149                 : 
    1150                 :     NS_IMETHOD SetIcon(const nsAString& anIconSpec) = 0;
    1151                 : 
    1152                 :     /**
    1153                 :      * Return this widget's origin in screen coordinates.
    1154                 :      *
    1155                 :      * @return screen coordinates stored in the x,y members
    1156                 :      */
    1157                 : 
    1158                 :     virtual nsIntPoint WidgetToScreenOffset() = 0;
    1159                 : 
    1160                 :     /**
    1161                 :      * Given the specified client size, return the corresponding window size,
    1162                 :      * which includes the area for the borders and titlebar. This method
    1163                 :      * should work even when the window is not yet visible.
    1164                 :      */
    1165                 :     virtual nsIntSize ClientToWindowSize(const nsIntSize& aClientSize) = 0;
    1166                 : 
    1167                 :     /**
    1168                 :      * Dispatches an event to the widget
    1169                 :      *
    1170                 :      */
    1171                 :     NS_IMETHOD DispatchEvent(nsGUIEvent* event, nsEventStatus & aStatus) = 0;
    1172                 : 
    1173                 :     /**
    1174                 :      * Enables the dropping of files to a widget (XXX this is temporary)
    1175                 :      *
    1176                 :      */
    1177                 :     NS_IMETHOD EnableDragDrop(bool aEnable) = 0;
    1178                 :    
    1179                 :     /**
    1180                 :      * Enables/Disables system mouse capture.
    1181                 :      * @param aCapture true enables mouse capture, false disables mouse capture 
    1182                 :      *
    1183                 :      */
    1184                 :     NS_IMETHOD CaptureMouse(bool aCapture) = 0;
    1185                 : 
    1186                 :     /**
    1187                 :      * Classify the window for the window manager. Mostly for X11.
    1188                 :      */
    1189                 :     NS_IMETHOD SetWindowClass(const nsAString& xulWinType) = 0;
    1190                 : 
    1191                 :     /**
    1192                 :      * Enables/Disables system capture of any and all events that would cause a
    1193                 :      * dropdown to be rolled up, This method ignores the aConsumeRollupEvent 
    1194                 :      * parameter when aDoCapture is FALSE
    1195                 :      * @param aDoCapture true enables capture, false disables capture 
    1196                 :      * @param aConsumeRollupEvent true consumes the rollup event, false dispatches rollup event
    1197                 :      *
    1198                 :      */
    1199                 :     NS_IMETHOD CaptureRollupEvents(nsIRollupListener * aListener, bool aDoCapture,
    1200                 :                                    bool aConsumeRollupEvent) = 0;
    1201                 : 
    1202                 :     /**
    1203                 :      * Bring this window to the user's attention.  This is intended to be a more
    1204                 :      * gentle notification than popping the window to the top or putting up an
    1205                 :      * alert.  See, for example, Win32 FlashWindow or the NotificationManager on
    1206                 :      * the Mac.  The notification should be suppressed if the window is already
    1207                 :      * in the foreground and should be dismissed when the user brings this window
    1208                 :      * to the foreground.
    1209                 :      * @param aCycleCount Maximum number of times to animate the window per system 
    1210                 :      *                    conventions. If set to -1, cycles indefinitely until 
    1211                 :      *                    window is brought into the foreground.
    1212                 :      */
    1213                 :     NS_IMETHOD GetAttention(PRInt32 aCycleCount) = 0;
    1214                 : 
    1215                 :     /**
    1216                 :      * Ask whether there user input events pending.  All input events are
    1217                 :      * included, including those not targeted at this nsIwidget instance.
    1218                 :      */
    1219                 :     virtual bool HasPendingInputEvent() = 0;
    1220                 : 
    1221                 :     /**
    1222                 :      * Called when when we need to begin secure keyboard input, such as when a password field
    1223                 :      * gets focus.
    1224                 :      *
    1225                 :      * NOTE: Calls to this method may not be nested and you can only enable secure keyboard input
    1226                 :      * for one widget at a time.
    1227                 :      */
    1228                 :     NS_IMETHOD BeginSecureKeyboardInput() = 0;
    1229                 : 
    1230                 :     /**
    1231                 :      * Called when when we need to end secure keyboard input, such as when a password field
    1232                 :      * loses focus.
    1233                 :      *
    1234                 :      * NOTE: Calls to this method may not be nested and you can only enable secure keyboard input
    1235                 :      * for one widget at a time.
    1236                 :      */
    1237                 :     NS_IMETHOD EndSecureKeyboardInput() = 0;
    1238                 : 
    1239                 :     /**
    1240                 :      * Set the background color of the window titlebar for this widget. On Mac,
    1241                 :      * for example, this will remove the grey gradient and bottom border and
    1242                 :      * instead show a single, solid color.
    1243                 :      *
    1244                 :      * Ignored on any platform that does not support it. Ignored by widgets that
    1245                 :      * do not represent windows.
    1246                 :      *
    1247                 :      * @param aColor  The color to set the title bar background to. Alpha values 
    1248                 :      *                other than fully transparent (0) are respected if possible  
    1249                 :      *                on the platform. An alpha of 0 will cause the window to 
    1250                 :      *                draw with the default style for the platform.
    1251                 :      *
    1252                 :      * @param aActive Whether the color should be applied to active or inactive
    1253                 :      *                windows.
    1254                 :      */
    1255                 :     NS_IMETHOD SetWindowTitlebarColor(nscolor aColor, bool aActive) = 0;
    1256                 : 
    1257                 :     /**
    1258                 :      * If set to true, the window will draw its contents into the titlebar
    1259                 :      * instead of below it.
    1260                 :      *
    1261                 :      * Ignored on any platform that does not support it. Ignored by widgets that
    1262                 :      * do not represent windows.
    1263                 :      * May result in a resize event, so should only be called from places where
    1264                 :      * reflow and painting is allowed.
    1265                 :      *
    1266                 :      * @param aState Whether drawing into the titlebar should be activated.
    1267                 :      */
    1268                 :     virtual void SetDrawsInTitlebar(bool aState) = 0;
    1269                 : 
    1270                 :     /*
    1271                 :      * Determine whether the widget shows a resize widget. If it does,
    1272                 :      * aResizerRect returns the resizer's rect.
    1273                 :      *
    1274                 :      * Returns false on any platform that does not support it.
    1275                 :      *
    1276                 :      * @param aResizerRect The resizer's rect in device pixels.
    1277                 :      * @return Whether a resize widget is shown.
    1278                 :      */
    1279                 :     virtual bool ShowsResizeIndicator(nsIntRect* aResizerRect) = 0;
    1280                 : 
    1281                 :     /**
    1282                 :      * Get the Thebes surface associated with this widget.
    1283                 :      */
    1284                 :     virtual gfxASurface *GetThebesSurface() = 0;
    1285                 : 
    1286                 :     /**
    1287                 :      * Return the popup that was last rolled up, or null if there isn't one.
    1288                 :      */
    1289                 :     virtual nsIContent* GetLastRollup() = 0;
    1290                 : 
    1291                 :     /**
    1292                 :      * Begin a window resizing drag, based on the event passed in.
    1293                 :      */
    1294                 :     NS_IMETHOD BeginResizeDrag(nsGUIEvent* aEvent, PRInt32 aHorizontal, PRInt32 aVertical) = 0;
    1295                 : 
    1296                 :     /**
    1297                 :      * Begin a window moving drag, based on the event passed in.
    1298                 :      */
    1299                 :     NS_IMETHOD BeginMoveDrag(nsMouseEvent* aEvent) = 0;
    1300                 : 
    1301                 :     enum Modifiers {
    1302                 :         CAPS_LOCK = 0x01, // when CapsLock is active
    1303                 :         NUM_LOCK = 0x02, // when NumLock is active
    1304                 :         SHIFT_L = 0x0100,
    1305                 :         SHIFT_R = 0x0200,
    1306                 :         CTRL_L = 0x0400,
    1307                 :         CTRL_R = 0x0800,
    1308                 :         ALT_L = 0x1000, // includes Option
    1309                 :         ALT_R = 0x2000,
    1310                 :         COMMAND_L = 0x4000,
    1311                 :         COMMAND_R = 0x8000,
    1312                 :         HELP = 0x10000,
    1313                 :         FUNCTION = 0x100000,
    1314                 :         NUMERIC_KEY_PAD = 0x01000000 // when the key is coming from the keypad
    1315                 :     };
    1316                 :     /**
    1317                 :      * Utility method intended for testing. Dispatches native key events
    1318                 :      * to this widget to simulate the press and release of a key.
    1319                 :      * @param aNativeKeyboardLayout a *platform-specific* constant.
    1320                 :      * On Mac, this is the resource ID for a 'uchr' or 'kchr' resource.
    1321                 :      * On Windows, it is converted to a hex string and passed to
    1322                 :      * LoadKeyboardLayout, see
    1323                 :      * http://msdn.microsoft.com/en-us/library/ms646305(VS.85).aspx
    1324                 :      * @param aNativeKeyCode a *platform-specific* keycode.
    1325                 :      * On Windows, this is the virtual key code.
    1326                 :      * @param aModifiers some combination of the above 'Modifiers' flags;
    1327                 :      * not all flags will apply to all platforms. Mac ignores the _R
    1328                 :      * modifiers. Windows ignores COMMAND, NUMERIC_KEY_PAD, HELP and
    1329                 :      * FUNCTION.
    1330                 :      * @param aCharacters characters that the OS would decide to generate
    1331                 :      * from the event. On Windows, this is the charCode passed by
    1332                 :      * WM_CHAR.
    1333                 :      * @param aUnmodifiedCharacters characters that the OS would decide
    1334                 :      * to generate from the event if modifier keys (other than shift)
    1335                 :      * were assumed inactive. Needed on Mac, ignored on Windows.
    1336                 :      * @return NS_ERROR_NOT_AVAILABLE to indicate that the keyboard
    1337                 :      * layout is not supported and the event was not fired
    1338                 :      */
    1339                 :     virtual nsresult SynthesizeNativeKeyEvent(PRInt32 aNativeKeyboardLayout,
    1340                 :                                               PRInt32 aNativeKeyCode,
    1341                 :                                               PRUint32 aModifierFlags,
    1342                 :                                               const nsAString& aCharacters,
    1343                 :                                               const nsAString& aUnmodifiedCharacters) = 0;
    1344                 : 
    1345                 :     /**
    1346                 :      * Utility method intended for testing. Dispatches native mouse events
    1347                 :      * may even move the mouse cursor. On Mac the events are guaranteed to
    1348                 :      * be sent to the window containing this widget, but on Windows they'll go
    1349                 :      * to whatever's topmost on the screen at that position, so for
    1350                 :      * cross-platform testing ensure that your window is at the top of the
    1351                 :      * z-order.
    1352                 :      * @param aPoint screen location of the mouse, in device
    1353                 :      * pixels, with origin at the top left
    1354                 :      * @param aNativeMessage *platform-specific* event type (e.g. on Mac,
    1355                 :      * NSMouseMoved; on Windows, MOUSEEVENTF_MOVE, MOUSEEVENTF_LEFTDOWN etc)
    1356                 :      * @param aModifierFlags *platform-specific* modifier flags (ignored
    1357                 :      * on Windows)
    1358                 :      */
    1359                 :     virtual nsresult SynthesizeNativeMouseEvent(nsIntPoint aPoint,
    1360                 :                                                 PRUint32 aNativeMessage,
    1361                 :                                                 PRUint32 aModifierFlags) = 0;
    1362                 : 
    1363                 :     /**
    1364                 :      * Activates a native menu item at the position specified by the index
    1365                 :      * string. The index string is a string of positive integers separated
    1366                 :      * by the "|" (pipe) character. The last integer in the string represents
    1367                 :      * the item index in a submenu located using the integers preceding it.
    1368                 :      *
    1369                 :      * Example: 1|0|4
    1370                 :      * In this string, the first integer represents the top-level submenu
    1371                 :      * in the native menu bar. Since the integer is 1, it is the second submeu
    1372                 :      * in the native menu bar. Within that, the first item (index 0) is a
    1373                 :      * submenu, and we want to activate the 5th item within that submenu.
    1374                 :      */
    1375                 :     virtual nsresult ActivateNativeMenuItemAt(const nsAString& indexString) = 0;
    1376                 : 
    1377                 :     /**
    1378                 :      * This is used for native menu system testing.
    1379                 :      *
    1380                 :      * Updates a native menu at the position specified by the index string.
    1381                 :      * The index string is a string of positive integers separated by the "|" 
    1382                 :      * (pipe) character.
    1383                 :      *
    1384                 :      * Example: 1|0|4
    1385                 :      * In this string, the first integer represents the top-level submenu
    1386                 :      * in the native menu bar. Since the integer is 1, it is the second submeu
    1387                 :      * in the native menu bar. Within that, the first item (index 0) is a
    1388                 :      * submenu, and we want to update submenu at index 4 within that submenu.
    1389                 :      *
    1390                 :      * If this is called with an empty string it forces a full reload of the
    1391                 :      * menu system.
    1392                 :      */
    1393                 :     virtual nsresult ForceUpdateNativeMenuAt(const nsAString& indexString) = 0;
    1394                 : 
    1395                 :     /*
    1396                 :      * Force Input Method Editor to commit the uncommitted input
    1397                 :      */
    1398                 :     NS_IMETHOD ResetInputState()=0;
    1399                 : 
    1400                 :     /*
    1401                 :      * Following methods relates to IME 'Opened'/'Closed' state.
    1402                 :      * 'Opened' means the user can input any character. I.e., users can input Japanese  
    1403                 :      * and other characters. The user can change the state to 'Closed'.
    1404                 :      * 'Closed' means the user can input ASCII characters only. This is the same as a
    1405                 :      * non-IME environment. The user can change the state to 'Opened'.
    1406                 :      * For more information is here.
    1407                 :      * http://bugzilla.mozilla.org/show_bug.cgi?id=16940#c48
    1408                 :      */
    1409                 : 
    1410                 :     /*
    1411                 :      * Destruct and don't commit the IME composition string.
    1412                 :      */
    1413                 :     NS_IMETHOD CancelIMEComposition() = 0;
    1414                 : 
    1415                 :     /*
    1416                 :      * Notifies the input context changes.
    1417                 :      */
    1418                 :     NS_IMETHOD_(void) SetInputContext(const InputContext& aContext,
    1419                 :                                       const InputContextAction& aAction) = 0;
    1420                 : 
    1421                 :     /*
    1422                 :      * Get current input context.
    1423                 :      */
    1424                 :     NS_IMETHOD_(InputContext) GetInputContext() = 0;
    1425                 : 
    1426                 :     /**
    1427                 :      * Set accelerated rendering to 'True' or 'False'
    1428                 :      */
    1429                 :     NS_IMETHOD SetAcceleratedRendering(bool aEnabled) = 0;
    1430                 : 
    1431                 :     /*
    1432                 :      * Get toggled key states.
    1433                 :      * aKeyCode should be NS_VK_CAPS_LOCK or  NS_VK_NUM_LOCK or
    1434                 :      * NS_VK_SCROLL_LOCK.
    1435                 :      * aLEDState is the result for current LED state of the key.
    1436                 :      * If the LED is 'ON', it returns TRUE, otherwise, FALSE.
    1437                 :      * If the platform doesn't support the LED state (or we cannot get the
    1438                 :      * state), this method returns NS_ERROR_NOT_IMPLEMENTED.
    1439                 :      */
    1440                 :     NS_IMETHOD GetToggledKeyState(PRUint32 aKeyCode, bool* aLEDState) = 0;
    1441                 : 
    1442                 :     /*
    1443                 :      * An editable node (i.e. input/textarea/design mode document)
    1444                 :      *  is receiving or giving up focus
    1445                 :      * aFocus is true if node is receiving focus
    1446                 :      * aFocus is false if node is giving up focus (blur)
    1447                 :      *
    1448                 :      * If this returns NS_ERROR_*, OnIMETextChange and OnIMESelectionChange
    1449                 :      * and OnIMEFocusChange(false) will be never called.
    1450                 :      *
    1451                 :      * If this returns NS_SUCCESS_IME_NO_UPDATES, OnIMEFocusChange(false)
    1452                 :      * will be called but OnIMETextChange and OnIMESelectionChange will NOT.
    1453                 :      */
    1454                 :     NS_IMETHOD OnIMEFocusChange(bool aFocus) = 0;
    1455                 : 
    1456                 :     /*
    1457                 :      * Text content of the focused node has changed
    1458                 :      * aStart is the starting offset of the change
    1459                 :      * aOldEnd is the ending offset of the change
    1460                 :      * aNewEnd is the caret offset after the change
    1461                 :      */
    1462                 :     NS_IMETHOD OnIMETextChange(PRUint32 aStart,
    1463                 :                                PRUint32 aOldEnd,
    1464                 :                                PRUint32 aNewEnd) = 0;
    1465                 : 
    1466                 :     /*
    1467                 :      * Selection has changed in the focused node
    1468                 :      */
    1469                 :     NS_IMETHOD OnIMESelectionChange(void) = 0;
    1470                 : 
    1471                 :     /*
    1472                 :      * Retrieves preference for IME updates
    1473                 :      */
    1474                 :     virtual nsIMEUpdatePreference GetIMEUpdatePreference() = 0;
    1475                 : 
    1476                 :     /*
    1477                 :      * Call this method when a dialog is opened which has a default button.
    1478                 :      * The button's rectangle should be supplied in aButtonRect.
    1479                 :      */ 
    1480                 :     NS_IMETHOD OnDefaultButtonLoaded(const nsIntRect &aButtonRect) = 0;
    1481                 : 
    1482                 :     /**
    1483                 :      * Compute the overridden system mouse scroll speed on the root content of
    1484                 :      * web pages.  The widget may set the same value as aOriginalDelta.  E.g.,
    1485                 :      * when the system scrolling settings were customized, widget can respect
    1486                 :      * the will of the user.
    1487                 :      *
    1488                 :      * This is called only when the mouse wheel event scrolls the root content
    1489                 :      * of the web pages by line.  In other words, this isn't called when the
    1490                 :      * mouse wheel event is used for zoom, page scroll and other special
    1491                 :      * actions.  And also this isn't called when the user doesn't use the
    1492                 :      * system wheel speed settings.
    1493                 :      *
    1494                 :      * @param aOriginalDelta   The delta value of the current mouse wheel
    1495                 :      *                         scrolling event.
    1496                 :      * @param aIsHorizontal    If TRUE, the scrolling direction is horizontal.
    1497                 :      *                         Otherwise, it's vertical.
    1498                 :      * @param aOverriddenDelta The overridden mouse scrolling speed.  This value
    1499                 :      *                         may be same as aOriginalDelta.
    1500                 :      */
    1501                 :     NS_IMETHOD OverrideSystemMouseScrollSpeed(PRInt32 aOriginalDelta,
    1502                 :                                               bool aIsHorizontal,
    1503                 :                                               PRInt32 &aOverriddenDelta) = 0;
    1504                 : 
    1505                 :     /**
    1506                 :      * Return true if this process shouldn't use platform widgets, and
    1507                 :      * so should use PuppetWidgets instead.  If this returns true, the
    1508                 :      * result of creating and using a platform widget is undefined,
    1509                 :      * and likely to end in crashes or other buggy behavior.
    1510                 :      */
    1511                 :     static bool
    1512               0 :     UsePuppetWidgets()
    1513                 :     {
    1514               0 :       return XRE_GetProcessType() == GeckoProcessType_Content;
    1515                 :     }
    1516                 : 
    1517                 :     /**
    1518                 :      * Allocate and return a "puppet widget" that doesn't directly
    1519                 :      * correlate to a platform widget; platform events and data must
    1520                 :      * be fed to it.  Currently used in content processes.  NULL is
    1521                 :      * returned if puppet widgets aren't supported in this build
    1522                 :      * config, on this platform, or for this process type.
    1523                 :      *
    1524                 :      * This function is called "Create" to match CreateInstance().
    1525                 :      * The returned widget must still be nsIWidget::Create()d.
    1526                 :      */
    1527                 :     static already_AddRefed<nsIWidget>
    1528                 :     CreatePuppetWidget(PBrowserChild *aTabChild);
    1529                 : 
    1530                 :     /**
    1531                 :      * Reparent this widget's native widget.
    1532                 :      * @param aNewParent the native widget of aNewParent is the new native
    1533                 :      *                   parent widget
    1534                 :      */
    1535                 :     NS_IMETHOD ReparentNativeWidget(nsIWidget* aNewParent) = 0;
    1536                 : 
    1537                 :     /**
    1538                 :      * Return the internal format of the default framebuffer for this
    1539                 :      * widget.
    1540                 :      */
    1541               0 :     virtual PRUint32 GetGLFrameBufferFormat() { return 0; /*GL_NONE*/ }
    1542                 : protected:
    1543                 : 
    1544                 :     // keep the list of children.  We also keep track of our siblings.
    1545                 :     // The ownership model is as follows: parent holds a strong ref to
    1546                 :     // the first element of the list, and each element holds a strong
    1547                 :     // ref to the next element in the list.  The prevsibling and
    1548                 :     // lastchild pointers are weak, which is fine as long as they are
    1549                 :     // maintained properly.
    1550                 :     nsCOMPtr<nsIWidget> mFirstChild;
    1551                 :     nsIWidget* mLastChild;
    1552                 :     nsCOMPtr<nsIWidget> mNextSibling;
    1553                 :     nsIWidget* mPrevSibling;
    1554                 : };
    1555                 : 
    1556                 : NS_DEFINE_STATIC_IID_ACCESSOR(nsIWidget, NS_IWIDGET_IID)
    1557                 : 
    1558                 : #endif // nsIWidget_h__

Generated by: LCOV version 1.7