Fix wxWebView documentation warnings.

[wxWidgets.git] / interface / wx / settings.h

diff --git a/interface/wx/settings.h b/interface/wx/settings.h
index 9acd7d301e552c5a4db030de78233f2267d2bca1..b2528fa8a665d26dc108fef4d088e1f46829ea87 100644 (file)
--- a/interface/wx/settings.h
+++ b/interface/wx/settings.h
@@ -3,22 +3,34 @@
 // Purpose:     interface of wxSystemSettings
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxSystemSettings
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 
 /**
     Possible values for wxSystemSettings::GetFont() parameter.
 /////////////////////////////////////////////////////////////////////////////
 
 
 /**
     Possible values for wxSystemSettings::GetFont() parameter.

+
+    These values map 1:1 the native values supported by the Windows' @c GetStockObject
+    function. Note that other ports (other than wxMSW) will try to provide meaningful
+    fonts but they usually map the same font to various @c wxSYS_*_FONT values.

 */
 enum wxSystemFont
 {
 */
 enum wxSystemFont
 {

-    wxSYS_OEM_FIXED_FONT = 10,   //!< Original equipment manufacturer dependent fixed-pitch font.
-    wxSYS_ANSI_FIXED_FONT,       //!< Windows fixed-pitch font.
-    wxSYS_ANSI_VAR_FONT,         //!< Windows variable-pitch (proportional) font.
-    wxSYS_SYSTEM_FONT,           //!< System font.
-    wxSYS_DEVICE_DEFAULT_FONT,   //!< Device-dependent font (Windows NT only).
-    wxSYS_DEFAULT_PALETTE,       //!< @todo docme.
-    wxSYS_SYSTEM_FIXED_FONT,     //!< @todo docme.
+    /// Original equipment manufacturer dependent fixed-pitch font.
+    wxSYS_OEM_FIXED_FONT = 10,
+
+    /// Windows fixed-pitch (monospaced) font.
+    wxSYS_ANSI_FIXED_FONT,
+
+    /// Windows variable-pitch (proportional) font.
+    wxSYS_ANSI_VAR_FONT,
+
+    /// System font. By default, the system uses the system font to draw menus,
+    /// dialog box controls, and text.
+    wxSYS_SYSTEM_FONT,
+
+    /// Device-dependent font (Windows NT and later only).
+    wxSYS_DEVICE_DEFAULT_FONT,

 
     /**
         Default font for user interface objects such as menus and dialog boxes.
 
     /**
         Default font for user interface objects such as menus and dialog boxes.


@@ -31,48 +43,65 @@ enum wxSystemFont
 
 /**
     Possible values for wxSystemSettings::GetColour() parameter.
 
 /**
     Possible values for wxSystemSettings::GetColour() parameter.

+
+    These values map 1:1 the native values supported by the Windows' @c GetSysColor
+    function. Note that other ports (other than wxMSW) will try to provide meaningful
+    colours but they usually map the same colour to various @c wxSYS_COLOUR_* values.

 */
 enum wxSystemColour
 {
     wxSYS_COLOUR_SCROLLBAR,           //!< The scrollbar grey area.
 */
 enum wxSystemColour
 {
     wxSYS_COLOUR_SCROLLBAR,           //!< The scrollbar grey area.

-    wxSYS_COLOUR_BACKGROUND,          //!< The desktop colour.
-    wxSYS_COLOUR_ACTIVECAPTION,       //!< Active window caption.
-    wxSYS_COLOUR_INACTIVECAPTION,     //!< Inactive window caption.
-    wxSYS_COLOUR_MENU,                //!< Menu background.
-    wxSYS_COLOUR_WINDOW,              //!< Window background.
-    wxSYS_COLOUR_WINDOWFRAME,         //!< Window frame.
-    wxSYS_COLOUR_MENUTEXT,            //!< Menu text.
-    wxSYS_COLOUR_WINDOWTEXT,          //!< Text in windows.
-    wxSYS_COLOUR_CAPTIONTEXT,         //!< Text in caption, size box and scrollbar arrow box.
-    wxSYS_COLOUR_ACTIVEBORDER,        //!< Active window border.
-    wxSYS_COLOUR_INACTIVEBORDER,      //!< Inactive window border.
-    wxSYS_COLOUR_APPWORKSPACE,        //!< Background colour MDI applications.
-    wxSYS_COLOUR_HIGHLIGHT,           //!< Item(s) selected in a control.
-    wxSYS_COLOUR_HIGHLIGHTTEXT,       //!< Text of item(s) selected in a control.
-    wxSYS_COLOUR_BTNFACE,             //!< Face shading on push buttons.
-    wxSYS_COLOUR_BTNSHADOW,           //!< Edge shading on push buttons.
-    wxSYS_COLOUR_GRAYTEXT,            //!< Greyed (disabled) text.
-    wxSYS_COLOUR_BTNTEXT,             //!< Text on push buttons.
-    wxSYS_COLOUR_INACTIVECAPTIONTEXT, //!< Colour of text in active captions.
-    wxSYS_COLOUR_BTNHIGHLIGHT,        //!< Highlight colour for buttons (same as wxSYS_COLOUR_3DHILIGHT).
-    wxSYS_COLOUR_3DDKSHADOW,          //!< Dark shadow for three-dimensional display elements.
+    wxSYS_COLOUR_DESKTOP,             //!< The desktop colour.
+    wxSYS_COLOUR_ACTIVECAPTION,       //!< Active window caption colour.
+    wxSYS_COLOUR_INACTIVECAPTION,     //!< Inactive window caption colour.
+    wxSYS_COLOUR_MENU,                //!< Menu background colour.
+    wxSYS_COLOUR_WINDOW,              //!< Window background colour.
+    wxSYS_COLOUR_WINDOWFRAME,         //!< Window frame colour.
+    wxSYS_COLOUR_MENUTEXT,            //!< Colour of the text used in the menus.
+    wxSYS_COLOUR_WINDOWTEXT,          //!< Colour of the text used in generic windows.
+    wxSYS_COLOUR_CAPTIONTEXT,         //!< Colour of the text used in captions, size boxes and scrollbar arrow boxes.
+    wxSYS_COLOUR_ACTIVEBORDER,        //!< Active window border colour.
+    wxSYS_COLOUR_INACTIVEBORDER,      //!< Inactive window border colour.
+    wxSYS_COLOUR_APPWORKSPACE,        //!< Background colour for MDI applications.
+    wxSYS_COLOUR_HIGHLIGHT,           //!< Colour of item(s) selected in a control.
+    wxSYS_COLOUR_HIGHLIGHTTEXT,       //!< Colour of the text of item(s) selected in a control.
+    wxSYS_COLOUR_BTNFACE,             //!< Face shading colour on push buttons.
+    wxSYS_COLOUR_BTNSHADOW,           //!< Edge shading colour on push buttons.
+    wxSYS_COLOUR_GRAYTEXT,            //!< Colour of greyed (disabled) text.
+    wxSYS_COLOUR_BTNTEXT,             //!< Colour of the text on push buttons.
+    wxSYS_COLOUR_INACTIVECAPTIONTEXT, //!< Colour of the text in active captions.
+    wxSYS_COLOUR_BTNHIGHLIGHT,        //!< Highlight colour for buttons.
+    wxSYS_COLOUR_3DDKSHADOW,          //!< Dark shadow colour for three-dimensional display elements.

     wxSYS_COLOUR_3DLIGHT,             //!< Light colour for three-dimensional display elements.
     wxSYS_COLOUR_INFOTEXT,            //!< Text colour for tooltip controls.
     wxSYS_COLOUR_INFOBK,              //!< Background colour for tooltip controls.
     wxSYS_COLOUR_3DLIGHT,             //!< Light colour for three-dimensional display elements.
     wxSYS_COLOUR_INFOTEXT,            //!< Text colour for tooltip controls.
     wxSYS_COLOUR_INFOBK,              //!< Background colour for tooltip controls.

+    wxSYS_COLOUR_LISTBOX,             //!< Background colour for list-like controls.
+    wxSYS_COLOUR_HOTLIGHT,            //!< Colour for a hyperlink or hot-tracked item.

 
 

-    wxSYS_COLOUR_DESKTOP = wxSYS_COLOUR_BACKGROUND,
-    wxSYS_COLOUR_3DFACE = wxSYS_COLOUR_BTNFACE,
-    wxSYS_COLOUR_3DSHADOW = wxSYS_COLOUR_BTNSHADOW,
-    wxSYS_COLOUR_BTNHILIGHT = wxSYS_COLOUR_BTNHIGHLIGHT,
-    wxSYS_COLOUR_3DHIGHLIGHT = wxSYS_COLOUR_BTNHIGHLIGHT,
-    wxSYS_COLOUR_3DHILIGHT = wxSYS_COLOUR_BTNHIGHLIGHT,
-
-    wxSYS_COLOUR_LISTBOX,             ///< Background colour for list-like contols.
-    wxSYS_COLOUR_HOTLIGHT,
+    /**
+        Right side colour in the color gradient of an active window's title bar.
+        @c wxSYS_COLOUR_ACTIVECAPTION specifies the left side color.
+    */

     wxSYS_COLOUR_GRADIENTACTIVECAPTION,
     wxSYS_COLOUR_GRADIENTACTIVECAPTION,

+
+    /**
+        Right side colour in the color gradient of an inactive window's title bar.
+        @c wxSYS_COLOUR_INACTIVECAPTION specifies the left side color.
+    */

     wxSYS_COLOUR_GRADIENTINACTIVECAPTION,
     wxSYS_COLOUR_GRADIENTINACTIVECAPTION,

+
+    /**
+        The colour used to highlight menu items when the menu appears as a flat menu.
+        The highlighted menu item is outlined with @c wxSYS_COLOUR_HIGHLIGHT.
+    */

     wxSYS_COLOUR_MENUHILIGHT,
     wxSYS_COLOUR_MENUHILIGHT,

+
+    /**
+        The background colour for the menu bar when menus appear as flat menus.
+        However, @c wxSYS_COLOUR_MENU continues to specify the background color of the menu popup.
+    */

     wxSYS_COLOUR_MENUBAR,
     wxSYS_COLOUR_MENUBAR,

+

     /**
         Text colour for list-like controls.
 
     /**
         Text colour for list-like controls.
 


@@ -80,7 +109,43 @@ enum wxSystemColour
      */
     wxSYS_COLOUR_LISTBOXTEXT,
 
      */
     wxSYS_COLOUR_LISTBOXTEXT,
 

+    /**
+        Text colour for the unfocused selection of list-like controls.
+
+        @since 2.9.1
+     */
+    wxSYS_COLOUR_LISTBOXHIGHLIGHTTEXT,
+

     wxSYS_COLOUR_MAX
     wxSYS_COLOUR_MAX

+
+
+
+    // synonyms:
+
+    wxSYS_COLOUR_BACKGROUND = wxSYS_COLOUR_DESKTOP,
+        //!< Synonym for @c wxSYS_COLOUR_DESKTOP.
+    wxSYS_COLOUR_3DFACE = wxSYS_COLOUR_BTNFACE,
+        //!< Synonym for @c wxSYS_COLOUR_BTNFACE.
+    wxSYS_COLOUR_3DSHADOW = wxSYS_COLOUR_BTNSHADOW,
+        //!< Synonym for @c wxSYS_COLOUR_BTNSHADOW.
+    wxSYS_COLOUR_BTNHILIGHT = wxSYS_COLOUR_BTNHIGHLIGHT,
+        //!< Synonym for @c wxSYS_COLOUR_BTNHIGHLIGHT.
+    wxSYS_COLOUR_3DHIGHLIGHT = wxSYS_COLOUR_BTNHIGHLIGHT,
+        //!< Synonym for @c wxSYS_COLOUR_BTNHIGHLIGHT.
+    wxSYS_COLOUR_3DHILIGHT = wxSYS_COLOUR_BTNHIGHLIGHT,
+        //!< Synonym for @c wxSYS_COLOUR_BTNHIGHLIGHT.
+
+    /**
+        Synonym for @c wxSYS_COLOUR_BTNFACE.
+
+        On wxMSW this colour should be used as the background colour of
+        wxFrames which are used as containers of controls; this is in fact the
+        same colour used for the borders of controls like e.g. wxNotebook or
+        for the background of e.g. wxPanel.
+
+        @since 2.9.0
+    */
+    wxSYS_COLOUR_FRAMEBK = wxSYS_COLOUR_BTNFACE

 };
 
 /**
 };
 
 /**


@@ -95,7 +160,6 @@ enum wxSystemMetric
     wxSYS_CURSOR_Y,           //!< Height of cursor.
     wxSYS_DCLICK_X,           //!< Width in pixels of rectangle within which two successive mouse clicks must fall to generate a double-click.
     wxSYS_DCLICK_Y,           //!< Height in pixels of rectangle within which two successive mouse clicks must fall to generate a double-click.
     wxSYS_CURSOR_Y,           //!< Height of cursor.
     wxSYS_DCLICK_X,           //!< Width in pixels of rectangle within which two successive mouse clicks must fall to generate a double-click.
     wxSYS_DCLICK_Y,           //!< Height in pixels of rectangle within which two successive mouse clicks must fall to generate a double-click.

-    wxSYS_DCLICK_MSEC,        //!< Maximal time, in milliseconds, which may pass between subsequent clicks for a double click to be generated.

     wxSYS_DRAG_X,             //!< Width in pixels of a rectangle centered on a drag point to allow for limited movement of the mouse pointer before a drag operation begins.
     wxSYS_DRAG_Y,             //!< Height in pixels of a rectangle centered on a drag point to allow for limited movement of the mouse pointer before a drag operation begins.
     wxSYS_EDGE_X,             //!< Width of a 3D border, in pixels.
     wxSYS_DRAG_X,             //!< Width in pixels of a rectangle centered on a drag point to allow for limited movement of the mouse pointer before a drag operation begins.
     wxSYS_DRAG_Y,             //!< Height in pixels of a rectangle centered on a drag point to allow for limited movement of the mouse pointer before a drag operation begins.
     wxSYS_EDGE_X,             //!< Width of a 3D border, in pixels.


@@ -128,7 +192,7 @@ enum wxSystemMetric
                               //!< visually in situations where it would otherwise present the information
                               //!< only in audible form; zero otherwise.
     wxSYS_SWAP_BUTTONS,       //!< Non-zero if the meanings of the left and right mouse buttons are swapped; zero otherwise.
                               //!< visually in situations where it would otherwise present the information
                               //!< only in audible form; zero otherwise.
     wxSYS_SWAP_BUTTONS,       //!< Non-zero if the meanings of the left and right mouse buttons are swapped; zero otherwise.

-    wxSYS_DCLICK_MSEC
+    wxSYS_DCLICK_MSEC         //!< Maximal time, in milliseconds, which may pass between subsequent clicks for a double click to be generated.

 };
 
 /**
 };
 
 /**


@@ -142,7 +206,7 @@ enum wxSystemFeature
 };
 
 /**
 };
 
 /**

-    Values for different screen designs.
+    Values for different screen designs. See wxSystemSettings::GetScreenType().

 */
 enum wxSystemScreenType
 {
 */
 enum wxSystemScreenType
 {


@@ -159,13 +223,14 @@ enum wxSystemScreenType
     @class wxSystemSettings
 
     wxSystemSettings allows the application to ask for details about the system.
     @class wxSystemSettings
 
     wxSystemSettings allows the application to ask for details about the system.

-    This can include settings such as standard colours, fonts,
-    and user interface element sizes.
+
+    This can include settings such as standard colours, fonts, and user interface 
+    element sizes.

 
     @library{wxcore}
 
     @library{wxcore}

-    @category{misc}
+    @category{cfg}

 
 

-    @see wxFont, wxColour
+    @see wxFont, wxColour, wxSystemOptions

 */
 class wxSystemSettings : public wxObject
 {
 */
 class wxSystemSettings : public wxObject
 {


@@ -180,13 +245,23 @@ public:
 
     /**
         Returns a system colour.
 
     /**
         Returns a system colour.

-        @a index can be one of the ::wxSystemColour enum values.
+
+        @param index 
+            Can be one of the ::wxSystemColour enum values.
+            
+        @return
+            The returned colour is always valid.

     */
     static wxColour GetColour(wxSystemColour index);
 
     /**
         Returns a system font.
     */
     static wxColour GetColour(wxSystemColour index);
 
     /**
         Returns a system font.

-        @a index can be one of the ::wxSystemFont enum values.
+
+        @param index 
+            Can be one of the ::wxSystemFont enum values.
+            
+        @return
+            The returned font is always valid.

     */
     static wxFont GetFont(wxSystemFont index);
 
     */
     static wxFont GetFont(wxSystemFont index);
 


@@ -197,7 +272,7 @@ public:
         The value of @a win determines if the metric returned is a global value or
         a wxWindow based value, in which case it might determine the widget, the
         display the window is on, or something similar. The window given should be as
         The value of @a win determines if the metric returned is a global value or
         a wxWindow based value, in which case it might determine the widget, the
         display the window is on, or something similar. The window given should be as

-        close to the metric as possible (e.g a wxTopLevelWindow in case of the
+        close to the metric as possible (e.g. a wxTopLevelWindow in case of the

         wxSYS_CAPTION_Y metric).
 
         @a index can be one of the ::wxSystemMetric enum values.
         wxSYS_CAPTION_Y metric).
 
         @a index can be one of the ::wxSystemMetric enum values.


@@ -216,5 +291,11 @@ public:
         The return value is one of the ::wxSystemScreenType enum values.
     */
     static wxSystemScreenType GetScreenType();
         The return value is one of the ::wxSystemScreenType enum values.
     */
     static wxSystemScreenType GetScreenType();

+
+    /**
+        Returns @true if the port has certain feature.
+        See the ::wxSystemFeature enum values.
+    */
+    static bool HasFeature(wxSystemFeature index);

 };
 
 };