This file is indexed.

/usr/include/cwidget/toplevel.h is in libcwidget-dev 0.5.17-4+b1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
// toplevel.h                          -*-c++-*-
//
//  Copyright 2000, 2005, 2007-2008 Daniel Burrows
//
//  This program is free software; you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation; either version 2 of the License, or
//  (at your option) any later version.
//
//  This program is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with this program; see the file COPYING.  If not, write to
//  the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
//  Boston, MA 02111-1307, USA.
//

/** \file toplevel.h
 *
 *  \brief Routines to manage the global cwidget state.
 *
 *  This file contains routines that manage the global state of the
 *  cwidget library: initializing and shutting it down, controlling
 *  its main loop, changing the top-level widget, etc.
 */

#ifndef TOPLEVEL_H
#define TOPLEVEL_H

#include <sigc++/signal.h>

#include <cwidget/generic/util/ref_ptr.h>

/** \brief The namespace containing everything defined by cwidget. */
namespace cwidget
{
  /** \brief Return the version number of the library. */
  std::string version();

  namespace threads
  {
    class mutex;
  }

  namespace widgets
  {
    class widget;
  }

  /** \brief The namespace containing functions to manage the global
   *  state of cwidget.
   *
   *  Routines in this namespace handle initializing and shutting down
   *  cwidget, running its main loop, setting the top-level widget,
   *  and other functions related to the top-level control structures
   *  of the library.
   */
  namespace toplevel
  {
    /** An event in the global event queue.  Events are dispatched
     *  serially by the main loop.
     */
    class event
    {
    public:
      virtual void dispatch() = 0;
      virtual ~event();
    };

    /** An event based on sigc++ slots.  This is important because it can
     *  avoid some timing issues that occur when an object is destroyed
     *  before its callback triggers.  However, you cannot construct one
     *  of these threadsafely unless you are EXTREMELY careful, because it
     *  involves a slot copy; as with other sigc++ stuff, I recommend that
     *  you only create these in the 'main thread'.  (of course, passing
     *  around pointers to the resulting object is just fine, as long as
     *  the final invocation is also in the main thread)
     */
    class slot_event : public event
    {
      sigc::slot0<void> the_slot;
    public:
      slot_event(const sigc::slot0<void> &_the_slot)
	: the_slot(_the_slot)
      {
      }

      void dispatch();
    };

    /** \brief Initializes curses and the global state of the cwidget
     *  library.
     */
    void init();

    /** \brief Installs signal handlers to cleanly shut down cwidget.
     *
     *  This is always invoked by cwidget::toplevel::init().  However,
     *  you might want to invoke it manually if you have removed the
     *  cwidget signal handlers (for instance, in order to invoke an
     *  external program).
     *
     *  Installs signal handlers for TERM, INT, QUIT, SEGV, and ABRT
     *  which restore the terminal and exit the program.
     */
    void install_sighandlers();

    /** Sets the top-level widget to the new value, returning the old
     *  top-level widget.  If the top-level widget is to be destroyed,
     *  IT IS THE CALLER'S RESPONSIBILITY TO CALL destroy() BEFORE
     *  DISCARDING THE REFERENCE!
     */
    util::ref_ptr<widgets::widget> settoplevel(const util::ref_ptr<widgets::widget> &widget);

    /** Posts a request to recalculate every widget's layout and update
     *  the screen.  May be called from any thread.
     */
    void queuelayout();

    /** \brief Immediately recalculates the layout of all widgets. */
    void layoutnow();

    //   Main loop handlers:

    /** \brief Start the main event loop.
     *
     *  This routine repeatedly removes events from the global queue
     *  and invokes event::dispatch() on them.  It terminates when
     *  exitmain() is invoked or when an exception is thrown.  In
     *  particular, callers should be prepared to catch
     *  cwidget::util::Exception instances:
     *
     *     catch(cwidget::util::Exception &e)
     *     {
     *     }
     *
     *  If an exception is thrown, the caller is responsible for
     *  invoking cwidget::toplevel::shutdown() to restore the terminal
     *  state.  A simple way of testing that your code catches
     *  exceptions correctly is to redirect stdin from /dev/null; this
     *  will throw an exception stating that the program cannot read
     *  from stdin.
     *
     *  \param synch Ignored; it is present for historical reasons and
     *  will be removed in a future release of cwidget.
     */
    void mainloop(int synch=0);

    /** Post the given event to the main event queue.  When the event
     *  comes off the queue, its dispatch method will be invoked and it
     *  will immediately be destroyed.
     *
     *  This method is thread-safe and is the main mechanism by which
     *  other threads should communicate with the main thread.
     */
    void post_event(event *ev);

    /** Dispatch any events in the event queue.  This is deprecated in
     *  favor of the more reliable approach of using threads and
     *  post_event.
     *
     *  \return \b true if pending input was found.
     */
    bool poll();

    void exitmain();
    // Exits the main loop.

    void redraw();
    // Redraws the screen completely from scratch

    /** Posts a request to redraw the screen; may be called from any thread. */
    void update();

    /** Executes any pending draws or redraws. */
    void tryupdate();

    /** Posts a request to update the cursor location; may be called from
     *  any thread.
     */
    void updatecursor();

    /** Hides all widgets and suspends Curses operation until
     *  resume() is called.  In addition, sets SIGCONT and SIGTSTP
     *  to SIG_DFL (appropriate if you'll be running subprocesses);
     *  resume() will restore these handlers.
     */
    void suspend();

    /** Hides all widgets and suspends Curses operation until
     *  resume() is called, but does NOT reset the SIGCONT and
     *  SIGTSTP handlers.
     */
    void suspend_without_signals();

    /** Does the same thing as suspend, except that it also
     *  destroys the top-level widget.  Call this when the program is
     *  exiting.
     */
    void shutdown();

    /** Returns to Curses mode after a suspend*, restoring any
     *  signal handlers that were modified by the suspend routine.
     */
    void resume();

    /** Invoke the given event in at least msecs from the current
     *  time.
     *
     *  \return a numerical identifier of the new event; you can use this
     *          number to delete it.
     */
    int addtimeout(event *ev, int msecs);

    /** Delete the event with the given identifier. */
    void deltimeout(int id);

    void handleresize();
    // Does anything needed to handle a window resize event.
    // FIXME: I --think-- that this is now redundant

    //  Return a mutex that is held whenever the main loop is processing
    //  events or drawing the screen.  The mutex can be held by other
    //  threads that want to do their own drawing or processing, although
    //  this is highly discouraged (use the event posting system instead
    //  to run code in the main loop).
    threads::mutex &get_mutex();

    /** \return the number of times that toplevel::suspend has been
     *  invoked since toplevel::init was invoked.
     *
     *  This can be used to detect when a suspend has occurred between
     *  when an event was posted and when it fired.  For instance, the
     *  input thread generates events that actually read from stdin,
     *  but if one of them fires after a suspend, the thread will get
     *  confused about how many events are trying to read and end up
     *  reading too many times and blowing up.
     */
    int get_suspend_count();

    extern sigc::signal0<void> main_hook;
    // Called right after we finish handling input in the mainloop.  Can
    // be used (eg) to insert extra actions to be performed after all
    // user-input (aptitude uses this to check for apt errors and pop up a
    // message about them)
  }
}

#endif