X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/2352862a7ee8440fdc2ae65baff31b73e40179d5..1aa1d260b558c1bf27f22fc317a4475d16789066:/interface/wx/defs.h

diff --git a/interface/wx/defs.h b/interface/wx/defs.h
index 2b2afd8f16..f9f1cc1541 100644
--- a/interface/wx/defs.h
+++ b/interface/wx/defs.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of global functions
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 
@@ -33,7 +33,7 @@ enum wxOrientation
     */
     wxBOTH                    = wxVERTICAL | wxHORIZONTAL,
 
-    /// A synonim for @c wxBOTH.
+    /// A synonym for @c wxBOTH.
     wxORIENTATION_MASK        = wxBOTH
 };
 
@@ -66,6 +66,16 @@ enum wxDirection
 */
 enum wxAlignment
 {
+    /**
+        A value different from any valid alignment value.
+
+        Note that you shouldn't use 0 for this as it's the value of (valid)
+        alignments wxALIGN_LEFT and wxALIGN_TOP.
+
+        @since 2.9.1
+     */
+    wxALIGN_INVALID           = -1,
+
     wxALIGN_NOT               = 0x0000,
     wxALIGN_CENTER_HORIZONTAL = 0x0100,
     wxALIGN_CENTRE_HORIZONTAL = wxALIGN_CENTER_HORIZONTAL,
@@ -136,33 +146,65 @@ enum wxBorder
 
 
 /**
-    Background styles. See wxWindow::SetBackgroundStyle().
+    Background styles.
+
+    @see wxWindow::SetBackgroundStyle()
 */
 enum wxBackgroundStyle
 {
-    /// Use the default background, as determined by
-    /// the system or the current theme.
+    /**
+        Default background style value indicating that the background may be
+        erased in the user-defined EVT_ERASE_BACKGROUND handler.
+
+        If no such handler is defined (or if it skips the event), the effect of
+        this style is the same as wxBG_STYLE_SYSTEM. If an empty handler (@em
+        not skipping the event) is defined, the effect is the same as
+        wxBG_STYLE_PAINT, i.e. the background is not erased at all until
+        EVT_PAINT handler is executed.
+
+        This is the only background style value for which erase background
+        events are generated at all.
+     */
+    wxBG_STYLE_ERASE,
+
+    /**
+        Use the default background, as determined by the system or the current
+        theme.
+
+        If the window has been assigned a non-default background colour, it
+        will be used for erasing its background. Otherwise the default
+        background (which might be a gradient or a pattern) will be used.
+
+        EVT_ERASE_BACKGROUND event will not be generated at all for windows
+        with this style.
+     */
     wxBG_STYLE_SYSTEM,
 
-    /// Use a solid colour for the background, this style is set automatically if you call
-    /// SetBackgroundColour() so you only need to set it explicitly if you had
-    /// changed the background style to something else before.
-    wxBG_STYLE_COLOUR,
+    /**
+        Indicates that the background is only erased in the user-defined
+        EVT_PAINT handler.
 
-    /// Don't draw the background at all, it's supposed that it is drawn by
-    /// the user-defined erase background event handler.
-    /// This style should be used to avoid flicker when the background is entirely
-    /// custom-drawn.
-    wxBG_STYLE_CUSTOM,
+        Using this style avoids flicker which would result from redrawing the
+        background twice if the EVT_PAINT handler entirely overwrites it. It
+        must not be used however if the paint handler leaves any parts of the
+        window unpainted as their contents is then undetermined. Only use it if
+        you repaint the whole window in your handler.
 
-    /// The background is (partially) transparent,this style is automatically set if you call
-    /// SetTransparent() which is used to set the transparency level.
-    wxBG_STYLE_TRANSPARENT
+        EVT_ERASE_BACKGROUND event will not be generated at all for windows
+        with this style.
+     */
+    wxBG_STYLE_PAINT
 };
 
 
 /**
-    Standard menu IDs.
+    Standard IDs.
+
+    Notice that some, but @em not all, of these IDs are also stock IDs, i.e.
+    you can use them for the button or menu items without specifying the label
+    which will be provided by the underlying platform itself. See @ref "the
+    list of stock items" for the subset of standard IDs which are stock IDs as
+    well.
 */
 enum wxStandardID
 {
@@ -444,13 +486,27 @@ enum wxDataFormatId
 /**
     Virtual keycodes used by wxKeyEvent and some other wxWidgets functions.
 
-    Note that the range @c 33 - @c 126 is reserved for the standard ASCII
-    characters and that the range @c 128 - @c 255 is reserved for the
-    extended ASCII characters (which are not really standard and thus should
-    be avoid in portable apps!).
+    Note that the range <code>0..255</code> corresponds to the characters of
+    the current locale, in particular the <code>32..127</code> subrange is for
+    the ASCII symbols, and all the special key values such as @c WXK_END lie
+    above this range.
 */
 enum wxKeyCode
 {
+    /**
+        No key.
+
+        This value is returned by wxKeyEvent::GetKeyCode() if there is no
+        non-Unicode representation for the pressed key (e.g. a Cyrillic letter
+        was entered when not using a Cyrillic locale) and by
+        wxKeyEvent::GetUnicodeKey() if there is no Unicode representation for
+        the key (this happens for the special, non printable, keys only, e.g.
+        WXK_HOME).
+
+        @since 2.9.2 (you can simply use 0 with previous versions).
+     */
+    WXK_NONE    =    0,
+
     WXK_BACK    =    8,     //!< Backspace.
     WXK_TAB     =    9,
     WXK_RETURN  =    13,
@@ -460,9 +516,11 @@ enum wxKeyCode
     WXK_DELETE  =    127,
 
     /**
-        These are, by design, not compatible with unicode characters.
-        If you want to get a unicode character from a key event, use
-        wxKeyEvent::GetUnicodeKey instead.
+        Special key values.
+
+        These are, by design, not compatible with Unicode characters.
+        If you want to get a Unicode character from a key event, use
+        wxKeyEvent::GetUnicodeKey() instead.
     */
     WXK_START   = 300,
     WXK_LBUTTON,
@@ -595,20 +653,19 @@ enum wxKeyModifier
 {
     wxMOD_NONE      = 0x0000,
     wxMOD_ALT       = 0x0001,
+    /** Ctlr Key, corresponds to Command key on OS X */
     wxMOD_CONTROL   = 0x0002,
     wxMOD_ALTGR     = wxMOD_ALT | wxMOD_CONTROL,
     wxMOD_SHIFT     = 0x0004,
     wxMOD_META      = 0x0008,
     wxMOD_WIN       = wxMOD_META,
-
-    /**
-        Notice that @c wxMOD_CMD should be used instead of @c wxMOD_CONTROL
-        in portable code to account for the fact that although
-        @c Control modifier exists under Mac OS, it is not used for the same
-        purpose as under Windows or Unix there while the special Mac-specific
-        @c Command modifier is used in exactly the same way.
-    */
-    wxMOD_CMD       = wxMOD_META,
+    
+    /** used to describe the true Ctrl Key under OSX, 
+    identic to @c wxMOD_CONTROL on other platforms */
+    wxMOD_RAW_CONTROL,
+    
+    /** deprecated, identic to @c wxMOD_CONTROL on all platforms */
+    wxMOD_CMD       = wxMOD_CONTROL,
     wxMOD_ALL       = 0xffff
 };
 
@@ -742,6 +799,15 @@ enum wxPaperSize
     wxPAPER_PENV_10_ROTATED     ///< PRC Envelope #10 Rotated 458 x 324 m
 };
 
+/**
+    Printing orientation
+*/
+
+enum wxPrintOrientation
+{
+   wxPORTRAIT,
+   wxLANDSCAPE
+};
 
 /**
     Duplex printing modes.