components/renderer_context_menu/render_view_context_menu_observer.h

   1 // Copyright 2014 The Chromium Authors
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef COMPONENTS_RENDERER_CONTEXT_MENU_RENDER_VIEW_CONTEXT_MENU_OBSERVER_H_
   6 #define COMPONENTS_RENDERER_CONTEXT_MENU_RENDER_VIEW_CONTEXT_MENU_OBSERVER_H_
   7
   8 #include "ui/gfx/geometry/rect.h"
   9
  10 namespace content {
  11 struct ContextMenuParams;
  12 }
  13
  14 // The interface used for implementing context-menu items. The following
  15 // instruction describe how to implement a context-menu item with this
  16 // interface.
  17 //
  18 // 1. Add command IDs for the context-menu items to 'chrome_command_ids.h'.
  19 //
  20 //   #define IDC_MY_COMMAND 99999
  21 //
  22 // 2. Add strings for the context-menu items to 'generated_sources.grd'.
  23 //
  24 //   <message name="IDS_MY_COMMAND" desc="...">
  25 //     My command
  26 //   </message>
  27 //
  28 // 3. Create a class that implements this interface. (It is a good idea to use
  29 // the RenderViewContextMenuProxy interface to avoid accessing the
  30 // RenderViewContextMenu class directly.)
  31 //
  32 //  class MyMenuObserver : public RenderViewContextMenuObserver {
  33 //   public:
  34 //    MyMenuObserver(RenderViewContextMenuProxy* p);
  35 //    ~MyMenuObserver() override;
  36 //
  37 //    void InitMenu(const content::ContextMenuParams& params) override;
  38 //    bool IsCommandIdSupported(int command_id) override;
  39 //    bool IsCommandIdEnabled(int command_id) override;
  40 //    void ExecuteCommand(int command_id) override;
  41 //
  42 //   private:
  43 //    RenderViewContextMenuProxy* proxy_;
  44 //  }
  45 //
  46 //  void MyMenuObserver::InitMenu(const content::ContextMenuParams& params) {
  47 //    proxy_->AddMenuItem(IDC_MY_COMMAND,...);
  48 //  }
  49 //
  50 //  bool MyMenuObserver::IsCommandIdSupported(int command_id) {
  51 //    return command_id == IDC_MY_COMMAND;
  52 //  }
  53 //
  54 //  bool MyMenuObserver::IsCommandIdEnabled(int command_id) {
  55 //    DCHECK(command_id == IDC_MY_COMMAND);
  56 //    return true;
  57 //  }
  58 //
  59 //  void MyMenuObserver::ExecuteCommand(int command_id) {
  60 //    DCHECK(command_id == IDC_MY_COMMAND);
  61 //  }
  62 //
  63 // 4. Add this observer class to the RenderViewContextMenu class. (It is good
  64 // to use std::unique_ptr<> so Chrome can create its instances only when it
  65 // needs.)
  66 //
  67 //  class RenderViewContextMenu {
  68 //    ...
  69 //   private:
  70 //    std::unique_ptr<MyMenuObserver> my_menu_observer_;
  71 //  };
  72 //
  73 // 5. Create its instance in InitMenu() and add it to the observer list of the
  74 // RenderViewContextMenu class.
  75 //
  76 //  void RenderViewContextMenu::InitMenu() {
  77 //    ...
  78 //    my_menu_observer_.reset(new MyMenuObserver(this));
  79 //    observers_.AddObserver(my_menu_observer_.get());
  80 //  }
  81 //
  82 //
  83 class RenderViewContextMenuObserver {
  84  public:
  85   virtual ~RenderViewContextMenuObserver() {}
  86
  87   // Called when the RenderViewContextMenu class initializes a context menu. We
  88   // usually call RenderViewContextMenuProxy::AddMenuItem() to add menu items
  89   // in this function.
  90   virtual void InitMenu(const content::ContextMenuParams& params) {}
  91
  92   // Called when the RenderViewContextMenu class asks whether an observer
  93   // listens for the specified command ID. If this function returns true, the
  94   // RenderViewContextMenu class calls IsCommandIdEnabled() or ExecuteCommand().
  95   virtual bool IsCommandIdSupported(int command_id);
  96
  97   // Called when the RenderViewContextMenu class sets the initial status of the
  98   // specified context-menu item. If we need to enable or disable a context-menu
  99   // item while showing, use RenderViewContextMenuProxy::UpdateMenuItem().
 100   virtual bool IsCommandIdChecked(int command_id);
 101   virtual bool IsCommandIdEnabled(int command_id);
 102
 103   // Called when a user selects the specified context-menu item. This is
 104   // only called when the observer returns true for IsCommandIdSupported()
 105   // for that |command_id|.
 106   virtual void ExecuteCommand(int command_id) {}
 107
 108   // Called when a user selects the specified context-menu item, including
 109   // command that is supported by other observers.
 110   virtual void CommandWillBeExecuted(int command_id) {}
 111
 112   virtual void OnMenuClosed() {}
 113
 114   virtual void OnContextMenuShown(const content::ContextMenuParams& params,
 115                                   const gfx::Rect& bounds_in_screen) {}
 116   //
 117   virtual void OnContextMenuViewBoundsChanged(
 118       const gfx::Rect& bounds_in_screen) {}
 119 };
 120
 121 #endif  // COMPONENTS_RENDERER_CONTEXT_MENU_RENDER_VIEW_CONTEXT_MENU_OBSERVER_H_