1// Copyright 2014 The Chromium Authors. All rights reserved.
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 CHROME_BROWSER_RENDERER_CONTEXT_MENU_RENDER_VIEW_CONTEXT_MENU_OBSERVER_H_
6#define CHROME_BROWSER_RENDERER_CONTEXT_MENU_RENDER_VIEW_CONTEXT_MENU_OBSERVER_H_
7
8namespace content {
9struct ContextMenuParams;
10}
11
12// The interface used for implementing context-menu items. The following
13// instruction describe how to implement a context-menu item with this
14// interface.
15//
16// 1. Add command IDs for the context-menu items to 'chrome_command_ids.h'.
17//
18//   #define IDC_MY_COMMAND 99999
19//
20// 2. Add strings for the context-menu items to 'generated_sources.grd'.
21//
22//   <message name="IDS_MY_COMMAND" desc="...">
23//     My command
24//   </message>
25//
26// 3. Create a class that implements this interface. (It is a good idea to use
27// the RenderViewContextMenuDelegate interface to avoid accessing the
28// RenderViewContextMenu class directly.)
29//
30//  class MyMenuObserver : public RenderViewContextMenuObserver {
31//   public:
32//    MyMenuObserver(RenderViewContextMenuDelegate* d);
33//    ~MyMenuObserver();
34//
35//    virtual void InitMenu(const content::ContextMenuParams& params) OVERRIDE;
36//    virtual bool IsCommandIdSupported(int command_id) OVERRIDE;
37//    virtual bool IsCommandIdEnabled(int command_id) OVERRIDE;
38//    virtual void ExecuteCommand(int command_id) OVERRIDE;
39//
40//   private:
41//    RenderViewContextMenuDelgate* delegate_;
42//  }
43//
44//  void MyMenuObserver::InitMenu(const content::ContextMenuParams& params) {
45//    delegate_->AddMenuItem(IDC_MY_COMMAND,...);
46//  }
47//
48//  bool MyMenuObserver::IsCommandIdSupported(int command_id) {
49//    return command_id == IDC_MY_COMMAND;
50//  }
51//
52//  bool MyMenuObserver::IsCommandIdEnabled(int command_id) {
53//    DCHECK(command_id == IDC_MY_COMMAND);
54//    return true;
55//  }
56//
57//  void MyMenuObserver::ExecuteCommand(int command_id) {
58//    DCHECK(command_id == IDC_MY_COMMAND);
59//  }
60//
61// 4. Add this observer class to the RenderViewContextMenu class. (It is good
62// to use scoped_ptr<> so Chrome can create its instances only when it needs.)
63//
64//  class RenderViewContextMenu {
65//    ...
66//   private:
67//    scoped_ptr<MyMenuObserver> my_menu_observer_;
68//  };
69//
70// 5. Create its instance in InitMenu() and add it to the observer list of the
71// RenderViewContextMenu class.
72//
73//  void RenderViewContextMenu::InitMenu() {
74//    ...
75//    my_menu_observer_.reset(new MyMenuObserver(this));
76//    observers_.AddObserver(my_menu_observer_.get());
77//  }
78//
79//
80class RenderViewContextMenuObserver {
81 public:
82  virtual ~RenderViewContextMenuObserver() {}
83
84  // Called when the RenderViewContextMenu class initializes a context menu. We
85  // usually call RenderViewContextMenuDelegate::AddMenuItem() to add menu items
86  // in this function.
87  virtual void InitMenu(const content::ContextMenuParams& params);
88
89  // Called when the RenderViewContextMenu class asks whether an observer
90  // listens for the specified command ID. If this function returns true, the
91  // RenderViewContextMenu class calls IsCommandIdEnabled() or ExecuteCommand().
92  virtual bool IsCommandIdSupported(int command_id);
93
94  // Called when the RenderViewContextMenu class sets the initial status of the
95  // specified context-menu item. If we need to enable or disable a context-menu
96  // item while showing, use RenderViewContextMenuDelegate::UpdateMenuItem().
97  virtual bool IsCommandIdChecked(int command_id);
98  virtual bool IsCommandIdEnabled(int command_id);
99
100  // Called when a user selects the specified context-menu item.
101  virtual void ExecuteCommand(int command_id);
102
103  // Called when a user closes the context menu without selecting any items.
104  virtual void OnMenuCancel();
105};
106
107#endif  // CHROME_BROWSER_RENDERER_CONTEXT_MENU_RENDER_VIEW_CONTEXT_MENU_OBSERVER_H_
108