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