First attempt to document raw bitmap access

[wxWidgets.git] / interface / apptrait.h

diff --git a/interface/apptrait.h b/interface/apptrait.h
index 6089c80cff640abaac676c0ded23f9314eedf715..7da10c02b965e21095364a4cc2de40a6515063d0 100644 (file)
--- a/interface/apptrait.h
+++ b/interface/apptrait.h
@@ -10,14 +10,18 @@
     @class wxAppTraits
     @wxheader{apptrait.h}
 
-    The @b wxAppTraits class defines various configurable aspects of a wxApp.
-    You can access it using wxApp::GetTraits function and you can create your
-    own wxAppTraits overriding the wxApp::CreateTraits function.
-
-    By default, wxWidgets creates a @c wxConsoleAppTraits object for console
-    applications (i.e. those applications linked against wxBase library only -
-    see the @ref page_libs page) and a @c wxGUIAppTraits object for GUI
+    The wxAppTraits class defines various configurable aspects of a wxApp.
+    You can access it using wxApp::GetTraits() function and you can create your
+    own wxAppTraits overriding the wxApp::CreateTraits() function.
+
+    Note that wxAppTraits is an abstract class since it contains many
+    pure virtual functions.
+    In fact, by default, wxWidgets creates a @c wxConsoleAppTraits object for
+    console applications (i.e. those applications linked against wxBase library
+    only - see the @ref page_libs page) and a @c wxGUIAppTraits object for GUI
     applications.
+    Both these classes are derived by wxAppTraits and represent concrete
+    implementation of the wxAppTraits interface.
 
     @library{wxbase}
     @category{appmanagement}
@@ -40,17 +44,20 @@ public:
     /**
         Creates the global font mapper object used for encodings/charset mapping.
     */
-    virtual wxFontMapper* CreateFontMapper();
+    virtual wxFontMapper* CreateFontMapper() = 0;
 
     /**
-        Creates the default log target for the application.
+        Creates a wxLog class for the application to use for logging errors.
+        The default implementation returns a new wxLogGui class.
+
+        @see wxLog
     */
-    virtual wxLog* CreateLogTarget();
+    virtual wxLog* CreateLogTarget() = 0;
 
     /**
         Creates the global object used for printing out messages.
     */
-    virtual wxMessageOutput* CreateMessageOutput();
+    virtual wxMessageOutput* CreateMessageOutput() = 0;
 
     /**
         Returns the renderer to use for drawing the generic controls (return
@@ -60,7 +67,7 @@ public:
 
         @note the returned pointer needs to be deleted by the caller.
     */
-    virtual wxRendererNative* CreateRenderer();
+    virtual wxRendererNative* CreateRenderer() = 0;
 
     /**
         This method returns the name of the desktop environment currently
@@ -69,14 +76,19 @@ public:
         to figure out, which desktop environment is running. The method
         returns an empty string otherwise and on all other platforms.
     */
-    virtual wxString GetDesktopEnvironment() const;
+    virtual wxString GetDesktopEnvironment() const = 0;
 
     /**
         Returns the wxStandardPaths object for the application.
         It's normally the same for wxBase and wxGUI except in the case of wxMac
         and wxCocoa.
+
+        @todo the real function returns a reference to wxStandardPathsBase;
+              user looking at these docs will write code:
+                    wxStandardPaths &ref = ...->GetStandardPaths();
+              which won't compile...
     */
-    virtual wxStandardPaths GetStandardPaths();
+    virtual wxStandardPaths& GetStandardPaths();
 
     /**
         Returns the wxWidgets port ID used by the running program and eventually
@@ -90,25 +102,24 @@ public:
         and put in given pointers the versions of the GTK library in use.
         See wxPlatformInfo for more details.
     */
-    virtual wxPortId GetToolkitVersion(int* major = NULL,
-                                       int* minor = NULL);
+    virtual wxPortId GetToolkitVersion(int* major = NULL, int* minor = NULL) const = 0;
 
     /**
         Returns @true if @c fprintf(stderr) goes somewhere, @false otherwise.
     */
-    virtual bool HasStderr();
+    virtual bool HasStderr() = 0;
 
     /**
         Returns @true if the library was built as wxUniversal.
         Always returns @false for wxBase-only apps.
     */
-    bool IsUsingUniversalWidgets() const;
+    virtual bool IsUsingUniversalWidgets() const = 0;
 
     /**
         Shows the assert dialog with the specified message in GUI mode or just prints
         the string to stderr in console mode.
         Returns @true to suppress subsequent asserts, @false to continue as before.
     */
-    virtual bool ShowAssertDialog(const wxString& msg);
+    virtual bool ShowAssertDialog(const wxString& msg) = 0;
 };