wxPython/src/_app.i

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        _app.i
   3 // Purpose:     SWIG interface for wxApp
   4 //
   5 // Author:      Robin Dunn
   6 //
   7 // Created:     9-Aug-2003
   8 // RCS-ID:      $Id$
   9 // Copyright:   (c) 2003 by Total Control Software
  10 // Licence:     wxWindows license
  11 /////////////////////////////////////////////////////////////////////////////
  12
  13 // Not a %module
  14
  15
  16 //---------------------------------------------------------------------------
  17 // TODOs:
  18 //
  19 // 1. Provide another app object that allows FilterEvent to be overloaded.
  20 // 2. Wrap wxAppTraits and allow wxApp::CreateTraits to be overloaded.
  21 //
  22 //---------------------------------------------------------------------------
  23 %newgroup;
  24
  25 %{
  26 %}
  27
  28 enum {
  29     wxPYAPP_ASSERT_SUPPRESS  = 1,
  30     wxPYAPP_ASSERT_EXCEPTION = 2,
  31     wxPYAPP_ASSERT_DIALOG    = 4,
  32     wxPYAPP_ASSERT_LOG       = 8
  33 };
  34
  35 enum
  36 {
  37     wxPRINT_WINDOWS = 1,
  38     wxPRINT_POSTSCRIPT = 2
  39 };
  40
  41
  42
  43
  44 class wxPyApp : public wxEvtHandler {
  45 public:
  46
  47     %pythonAppend wxPyApp
  48        "self._setCallbackInfo(self, PyApp)
  49         self._setOORInfo(self)";
  50
  51     DocStr(wxPyApp,
  52            "Create a new application object, starting the bootstrap process.");
  53     %extend {
  54         wxPyApp() {
  55             wxPythonApp = new wxPyApp();
  56             return wxPythonApp;
  57         }
  58     }
  59
  60     ~wxPyApp();
  61
  62     void _setCallbackInfo(PyObject* self, PyObject* _class);
  63
  64
  65     DocDeclStr(
  66         wxString, GetAppName() const,
  67         "Get the application name.");
  68     DocDeclStr(
  69         void, SetAppName(const wxString& name),
  70         "Set the application name. This value may be used automatically\n"
  71         "by wx.Config and such.");
  72
  73     DocDeclStr(
  74         wxString, GetClassName() const,
  75         "Get the application's class name.");
  76     DocDeclStr(
  77         void, SetClassName(const wxString& name),
  78         "Set the application's class name. This value may be used for X-resources if\n"
  79         "applicable for the platform");
  80
  81     DocDeclStr(
  82         const wxString&, GetVendorName() const,
  83         "Get the application's vendor name.");
  84     DocDeclStr(
  85         void, SetVendorName(const wxString& name),
  86         "Set the application's vendor name. This value may be used automatically\n"
  87         "by wx.Config and such.");
  88
  89
  90     DocDeclStr(
  91         wxAppTraits*, GetTraits(),
  92         "Create the app traits object to which we delegate for everything which either\n"
  93         "should be configurable by the user (then he can change the default behaviour\n"
  94         "simply by overriding CreateTraits() and returning his own traits object) or\n"
  95         "which is GUI/console dependent as then wx.AppTraits allows us to abstract the\n"
  96         "differences behind the common facade");
  97
  98
  99     DocDeclStr(
 100         virtual void, ProcessPendingEvents(),
 101         "Process all events in the Pending Events list -- it is necessary to call this\n"
 102         "function to process posted events. This happens during each event loop\n"
 103         "iteration.");
 104
 105
 106     DocDeclStr(
 107         virtual bool, Yield(bool onlyIfNeeded = False),
 108         "Process all currently pending events right now, instead of waiting until\n"
 109         "return to the event loop.  It is an error to call Yield() recursively unless\n"
 110         "the value of onlyIfNeeded is True.\n"
 111         "\n"
 112         "WARNING: This function is dangerous as it can lead to unexpected\n"
 113         "         reentrancies (i.e. when called from an event handler it\n"
 114         "         may result in calling the same event handler again), use\n"
 115         "         with _extreme_ care or, better, don't use at all!\n");
 116
 117
 118     DocDeclStr(
 119         virtual void, WakeUpIdle(),
 120         "Make sure that idle events are sent again");
 121
 122
 123     DocDeclStr(
 124         virtual int, MainLoop(),
 125         "Execute the main GUI loop, the function returns when the loop ends.");
 126
 127
 128     DocDeclStr(
 129         virtual void, Exit(),
 130         "Exit the main loop thus terminating the application.");
 131
 132
 133     DocDeclStr(
 134         virtual void, ExitMainLoop(),
 135         "Exit the main GUI loop during the next iteration (i.e. it does not\n"
 136         "stop the program immediately!)");
 137
 138
 139     DocDeclStr(
 140         virtual bool, Pending(),
 141         "Returns True if there are unprocessed events in the event queue.");
 142
 143
 144     DocDeclStr(
 145         virtual bool, Dispatch(),
 146         "Process the first event in the event queue (blocks until an event\n"
 147         "appears if there are none currently)");
 148
 149
 150     DocDeclStr(
 151         virtual bool, ProcessIdle(),
 152         "Called from the MainLoop when the application becomes idle and sends an\n"
 153         "IdleEvent to all interested parties.  Returns True is more idle events are\n"
 154         "needed, False if not.");
 155
 156
 157     DocDeclStr(
 158         virtual bool, SendIdleEvents(wxWindow* win, wxIdleEvent& event),
 159         "Send idle event to window and all subwindows.  Returns True if more idle time\n"
 160         "is requested.");
 161
 162
 163     DocDeclStr(
 164         virtual bool, IsActive() const,
 165         "Return True if our app has focus.");
 166
 167
 168     DocDeclStr(
 169         void, SetTopWindow(wxWindow *win),
 170         "Set the \"main\" top level window");
 171
 172     DocDeclStr(
 173         virtual wxWindow*, GetTopWindow() const,
 174         "Return the \"main\" top level window (if it hadn't been set previously with\n"
 175         "SetTopWindow(), will return just some top level window and, if there not any,\n"
 176         "will return None)");
 177
 178
 179     DocDeclStr(
 180         void, SetExitOnFrameDelete(bool flag),
 181         "Control the exit behaviour: by default, the program will exit the main loop\n"
 182         "(and so, usually, terminate) when the last top-level program window is\n"
 183         "deleted.  Beware that if you disable this behaviour (with\n"
 184         "SetExitOnFrameDelete(False)), you'll have to call ExitMainLoop() explicitly\n"
 185         "from somewhere.\n");
 186
 187
 188     DocDeclStr(
 189         bool, GetExitOnFrameDelete() const,
 190         "Get the current exit behaviour setting.");
 191
 192 #if 0
 193     // Get display mode that is in use. This is only used in framebuffer
 194     // wxWin ports (such as wxMGL).
 195     virtual wxVideoMode GetDisplayMode() const;
 196
 197     // Set display mode to use. This is only used in framebuffer wxWin
 198     // ports (such as wxMGL). This method should be called from
 199     // wxApp::OnInitGui
 200     virtual bool SetDisplayMode(const wxVideoMode& info);
 201 #endif
 202
 203
 204     DocDeclStr(
 205         void, SetUseBestVisual( bool flag ),
 206         "Set whether the app should try to use the best available visual on systems\n"
 207         "where more than one is available, (Sun, SGI, XFree86 4, etc.)");
 208
 209     DocDeclStr(
 210         bool, GetUseBestVisual() const,
 211         "Get current UseBestVisual setting.");
 212
 213
 214     // set/get printing mode: see wxPRINT_XXX constants.
 215     //
 216     // default behaviour is the normal one for Unix: always use PostScript
 217     // printing.
 218     virtual void SetPrintMode(int mode);
 219     int GetPrintMode() const;
 220
 221
 222     DocDeclStr(
 223         void, SetAssertMode(int mode),
 224         "Set the OnAssert behaviour for debug and hybrid builds.  The following flags\n"
 225         "may be or'd together:\n"
 226         "\n"
 227         " wx.PYAPP_ASSERT_SUPPRESS         Don't do anything\n"
 228         " wx.PYAPP_ASSERT_EXCEPTION        Turn it into a Python exception if possible (default)\n"
 229         " wx.PYAPP_ASSERT_DIALOG           Display a message dialog\n"
 230         " wx.PYAPP_ASSERT_LOG              Write the assertion info to the wx.Log\n");
 231
 232     DocDeclStr(
 233         int,  GetAssertMode(),
 234         "Get the current OnAssert behaviour setting.");
 235
 236
 237     static bool GetMacSupportPCMenuShortcuts();
 238     static long GetMacAboutMenuItemId();
 239     static long GetMacPreferencesMenuItemId();
 240     static long GetMacExitMenuItemId();
 241     static wxString GetMacHelpMenuTitleName();
 242
 243     static void SetMacSupportPCMenuShortcuts(bool val);
 244     static void SetMacAboutMenuItemId(long val);
 245     static void SetMacPreferencesMenuItemId(long val);
 246     static void SetMacExitMenuItemId(long val);
 247     static void SetMacHelpMenuTitleName(const wxString& val);
 248
 249
 250     DocDeclStr(
 251         void, _BootstrapApp(),
 252         "For internal use only");
 253
 254     DocStr(GetComCtl32Version,
 255            "Returns 400, 470, 471, etc. for comctl32.dll 4.00, 4.70, 4.71 or
 256 0 if it wasn't found at all.  Raises an exception on non-Windows
 257 platforms.");
 258 #ifdef __WXMSW__
 259     static int GetComCtl32Version();
 260 #else
 261     %extend {
 262         static int GetComCtl32Version()
 263             { wxPyRaiseNotImplemented(); return 0; }
 264     }
 265 #endif
 266 };
 267
 268
 269
 270 //---------------------------------------------------------------------------
 271 %newgroup;
 272
 273
 274 DocDeclStr(
 275     void,  wxExit(),
 276     "Force an exit of the application.  Convenience for wx.GetApp().Exit()");
 277
 278
 279 DocDeclStr(
 280     bool, wxYield(),
 281     "Yield to other apps/messages.  Convenience for wx.GetApp().Yield()");
 282
 283 DocDeclStr(
 284     bool, wxYieldIfNeeded(),
 285     "Yield to other apps/messages.  Convenience for wx.GetApp().Yield(True)");
 286
 287
 288 DocDeclStr(
 289     bool, wxSafeYield(wxWindow* win=NULL, bool onlyIfNeeded=False),
 290     "This function is similar to wx.Yield, except that it disables the user input\n"
 291     "to all program windows before calling wx.Yield and re-enables it again\n"
 292     "afterwards. If win is not None, this window will remain enabled, allowing the\n"
 293     "implementation of some limited user interaction.\n"
 294     "\n"
 295     "Returns the result of the call to wx.Yield.");
 296
 297
 298 DocDeclStr(
 299     void,  wxWakeUpIdle(),
 300     "Cause the message queue to become empty again, so idle events will be sent.");
 301
 302
 303 DocDeclStr(
 304     void, wxPostEvent(wxEvtHandler *dest, wxEvent& event),
 305     "Send an event to a window or other wx.EvtHandler to be processed later.");
 306
 307
 308 DocStr(wxApp_CleanUp,
 309        "For internal use only, it is used to cleanup after wxWindows when Python shuts down.");
 310 %inline %{
 311     void wxApp_CleanUp() {
 312         __wxPyCleanup();
 313     }
 314 %}
 315
 316
 317 DocStr(wxGetApp,
 318        "Return a reference to the current wx.App object.");
 319 %inline %{
 320     wxPyApp* wxGetApp() {
 321         return (wxPyApp*)wxTheApp;
 322     }
 323 %}
 324
 325
 326 //---------------------------------------------------------------------------
 327 // Include some extra wxApp related python code here
 328
 329 %pythoncode "_app_ex.py"
 330
 331 //---------------------------------------------------------------------------
 332