Note that CanCut / CanCopy / CanPaste are not currently supported on the OSX WebKit...

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

diff --git a/interface/wx/defs.h b/interface/wx/defs.h
index a04816e6f91ab99b48ed1bf7c9918a4c45da1a2a..2513b04c381ce152e31fa2dd3bd511b2237293b6 100644 (file)
--- a/interface/wx/defs.h
+++ b/interface/wx/defs.h
@@ -3,10 +3,14 @@
 // Purpose:     interface of global functions
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of global functions
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

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

 /////////////////////////////////////////////////////////////////////////////
 
 
 /////////////////////////////////////////////////////////////////////////////
 
 

+// ----------------------------------------------------------------------------
+// enumerations
+// ----------------------------------------------------------------------------
+

 /**
     Generic flags.
 */
 /**
     Generic flags.
 */


@@ -16,7 +20,6 @@ enum wxGeometryCentre
     wxCENTER                  = wxCENTRE
 };
 
     wxCENTER                  = wxCENTRE
 };
 

-

 /**
     A generic orientation value.
 */
 /**
     A generic orientation value.
 */


@@ -30,7 +33,7 @@ enum wxOrientation
     */
     wxBOTH                    = wxVERTICAL | wxHORIZONTAL,
 
     */
     wxBOTH                    = wxVERTICAL | wxHORIZONTAL,
 

-    /// A synonim for @c wxBOTH.
+    /// A synonym for @c wxBOTH.

     wxORIENTATION_MASK        = wxBOTH
 };
 
     wxORIENTATION_MASK        = wxBOTH
 };
 


@@ -63,6 +66,16 @@ enum wxDirection
 */
 enum wxAlignment
 {
 */
 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,
     wxALIGN_NOT               = 0x0000,
     wxALIGN_CENTER_HORIZONTAL = 0x0100,
     wxALIGN_CENTRE_HORIZONTAL = wxALIGN_CENTER_HORIZONTAL,


@@ -133,33 +146,65 @@ enum wxBorder
 
 
 /**
 
 
 /**

-    Background styles. See wxWindow::SetBackgroundStyle().
+    Background styles.
+
+    @see wxWindow::SetBackgroundStyle()

 */
 enum wxBackgroundStyle
 {
 */
 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,
 
     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
 {
 */
 enum wxStandardID
 {


@@ -439,21 +484,43 @@ enum wxDataFormatId
 };
 
 /**
 };
 
 /**

-    Virtual keycodes
+    Virtual keycodes used by wxKeyEvent and some other wxWidgets functions.
+
+    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
 {
 */
 enum wxKeyCode
 {

-    WXK_BACK    =    8,
+    /**
+        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,
     WXK_ESCAPE  =    27,
     WXK_SPACE   =    32,
     WXK_TAB     =    9,
     WXK_RETURN  =    13,
     WXK_ESCAPE  =    27,
     WXK_SPACE   =    32,

+

     WXK_DELETE  =    127,
 
     /**
     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,
     */
     WXK_START   = 300,
     WXK_LBUTTON,


@@ -733,6 +800,15 @@ enum wxPaperSize
     wxPAPER_PENV_10_ROTATED     ///< PRC Envelope #10 Rotated 458 x 324 m
 };
 
     wxPAPER_PENV_10_ROTATED     ///< PRC Envelope #10 Rotated 458 x 324 m
 };
 

+/**
+    Printing orientation
+*/
+
+enum wxPrintOrientation
+{
+   wxPORTRAIT,
+   wxLANDSCAPE
+};

 
 /**
     Duplex printing modes.
 
 /**
     Duplex printing modes.


@@ -767,6 +843,110 @@ enum wxUpdateUI
 };
 
 
 };
 
 

+// ----------------------------------------------------------------------------
+// constants
+// ----------------------------------------------------------------------------
+
+/**
+    C99-like sized MIN/MAX constants for all integer types.
+
+    For each @c n in the set 8, 16, 32, 64 we define @c wxINTn_MIN, @c
+    wxINTn_MAX and @c wxUINTc_MAX (@c wxUINTc_MIN is always 0 and so is not
+    defined).
+ */
+//@{
+#define wxINT8_MIN CHAR_MIN
+#define wxINT8_MAX CHAR_MAX
+#define wxUINT8_MAX UCHAR_MAX
+
+#define wxINT16_MIN SHRT_MIN
+#define wxINT16_MAX SHRT_MAX
+#define wxUINT16_MAX USHRT_MAX
+
+#define wxINT32_MIN INT_MIN-or-LONG_MIN
+#define wxINT32_MAX INT_MAX-or-LONG_MAX
+#define wxUINT32_MAX UINT_MAX-or-LONG_MAX
+
+#define wxINT64_MIN LLONG_MIN
+#define wxINT64_MAX LLONG_MAX
+#define wxUINT64_MAX ULLONG_MAX
+//@}
+
+// ----------------------------------------------------------------------------
+// types
+// ----------------------------------------------------------------------------
+
+/** The type for screen and DC coordinates. */
+typedef int wxCoord;
+
+/** A special value meaning "use default coordinate". */
+wxCoord wxDefaultCoord = -1;
+
+//@{
+/** 8 bit type (the mapping is more complex than a simple @c typedef and is not shown here). */
+typedef signed char wxInt8;
+typedef unsigned char wxUint8;
+typedef wxUint8 wxByte;
+//@}
+
+//@{
+/** 16 bit type (the mapping is more complex than a simple @c typedef and is not shown here). */
+typedef signed short wxInt16;
+typedef unsigned short wxUint16;
+typedef wxUint16 wxWord;
+typedef wxUint16 wxChar16;
+//@}
+
+//@{
+/** 32 bit type (the mapping is more complex than a simple @c typedef and is not shown here). */
+typedef int wxInt32;
+typedef unsigned int wxUint32;
+typedef wxUint32 wxDword;
+typedef wxUint32 wxChar32;
+//@}
+
+//@{
+/** 64 bit type (the mapping is more complex than a simple @c typedef and is not shown here). */
+typedef wxLongLong_t wxInt64;
+typedef wxULongLong_t wxUint64;
+//@}
+
+//@{
+/**
+    Signed and unsigned integral types big enough to contain all of @c long,
+    @c size_t and @c void*.
+    (The mapping is more complex than a simple @c typedef and is not shown here).
+*/
+typedef ssize_t wxIntPtr;
+typedef size_t wxUIntPtr;
+//@}
+
+
+/**
+    32 bit IEEE float ( 1 sign, 8 exponent bits, 23 fraction bits ).
+    (The mapping is more complex than a simple @c typedef and is not shown here).
+*/
+typedef float wxFloat32;
+
+
+/**
+    64 bit IEEE float ( 1 sign, 11 exponent bits, 52 fraction bits ).
+    (The mapping is more complex than a simple @c typedef and is not shown here).
+*/
+typedef double wxFloat64;
+
+/**
+    Native fastest representation that has at least wxFloat64 precision, so use
+    the IEEE types for storage, and this for calculations.
+    (The mapping is more complex than a simple @c typedef and is not shown here).
+*/
+typedef double wxDouble;
+
+
+
+// ----------------------------------------------------------------------------
+// macros
+// ----------------------------------------------------------------------------

 
 
 /** @addtogroup group_funcmacro_byteorder */
 
 
 /** @addtogroup group_funcmacro_byteorder */


@@ -842,9 +1022,9 @@ enum wxUpdateUI
     In such case, this macro can be used to disable the automatic assignment
     operator generation.
 
     In such case, this macro can be used to disable the automatic assignment
     operator generation.
 

-    @see DECLARE_NO_COPY_CLASS()
+    @see wxDECLARE_NO_COPY_CLASS()

  */
  */

-#define DECLARE_NO_ASSIGN_CLASS(classname)
+#define wxDECLARE_NO_ASSIGN_CLASS(classname)

 
 /**
     This macro can be used in a class declaration to disable the generation of
 
 /**
     This macro can be used in a class declaration to disable the generation of


@@ -869,27 +1049,47 @@ enum wxUpdateUI
 
     private:
         // widgets can't be copied
 
     private:
         // widgets can't be copied

-        DECLARE_NO_COPY_CLASS(FooWidget)
+        wxDECLARE_NO_COPY_CLASS(FooWidget);

     };
     @endcode
 
     };
     @endcode
 

-    Notice that a semicolon should not be used after this macro and that it
-    changes the access specifier to private internally so it is better to use
-    it at the end of the class declaration.
+    Notice that a semicolon must be used after this macro and that it changes
+    the access specifier to private internally so it is better to use it at the
+    end of the class declaration.
+
+    @see wxDECLARE_NO_ASSIGN_CLASS(), wxDECLARE_NO_COPY_TEMPLATE_CLASS()

  */
  */

-#define DECLARE_NO_COPY_CLASS(classname)
+#define wxDECLARE_NO_COPY_CLASS(classname)

 
 /**
 
 /**

-    Equivalent of DECLARE_NO_COPY_CLASS() for template classes.
+    Analog of wxDECLARE_NO_COPY_CLASS() for template classes.

 
     This macro can be used for template classes (with a single template
 
     This macro can be used for template classes (with a single template

-    parameter) for the same purpose as DECLARE_NO_COPY_CLASS() is used with the
+    parameter) for the same purpose as wxDECLARE_NO_COPY_CLASS() is used with the

     non-template classes.
 
     @param classname The name of the template class.
     @param arg The name of the template parameter.
     non-template classes.
 
     @param classname The name of the template class.
     @param arg The name of the template parameter.

+
+    @see wxDECLARE_NO_COPY_TEMPLATE_CLASS_2
+ */
+#define wxDECLARE_NO_COPY_TEMPLATE_CLASS(classname, arg)
+
+/**
+    Analog of wxDECLARE_NO_COPY_TEMPLATE_CLASS() for templates with 2
+    parameters.
+
+    This macro can be used for template classes with two template
+    parameters for the same purpose as wxDECLARE_NO_COPY_CLASS() is used with
+    the non-template classes.
+
+    @param classname The name of the template class.
+    @param arg1 The name of the first template parameter.
+    @param arg2 The name of the second template parameter.
+
+    @see wxDECLARE_NO_COPY_TEMPLATE_CLASS

  */
  */

-#define DECLARE_NO_COPY_TEMPLATE_CLASS(classname, arg)
+#define wxDECLARE_NO_COPY_TEMPLATE_CLASS_2(classname, arg1, arg2)

 
 /**
     A function which deletes and nulls the pointer.
 
 /**
     A function which deletes and nulls the pointer.


@@ -978,7 +1178,7 @@ template <typename T> wxDELETEA(T*& array);
     public:
         // OldMethod() is deprecated, use NewMethod() instead
         void NewMethod();
     public:
         // OldMethod() is deprecated, use NewMethod() instead
         void NewMethod();

-        wxDEPRECATED_INLINE( void OldMethod(), NewMethod() );
+        wxDEPRECATED_INLINE( void OldMethod(), NewMethod(); )

     };
     @endcode
 
     };
     @endcode
 


@@ -986,6 +1186,40 @@ template <typename T> wxDELETEA(T*& array);
 */
 #define wxDEPRECATED_INLINE(func, body)
 
 */
 #define wxDEPRECATED_INLINE(func, body)
 

+/**
+    A helper macro allowing to easily define a simple deprecated accessor.
+
+    Compared to wxDEPRECATED_INLINE() it saves a @c return statement and,
+    especially, a strangely looking semicolon inside a macro.
+
+    Example of use
+    @code
+    class wxFoo
+    {
+    public:
+        int GetValue() const { return m_value; }
+
+        // this one is deprecated because it was erroneously non-const
+        wxDEPRECATED_ACCESSOR( int GetValue(), m_value )
+
+    private:
+        int m_value;
+    };
+    @endcode
+ */
+#define wxDEPRECATED_ACCESSOR(func, what)
+
+/**
+    Combination of wxDEPRECATED_BUT_USED_INTERNALLY() and wxDEPRECATED_INLINE().
+
+    This macro should be used for deprecated functions called by the library
+    itself (usually for backwards compatibility reasons) and which are defined
+    inline.
+
+    @header{wx/defs.h}
+*/
+#define wxDEPRECATED_BUT_USED_INTERNALLY_INLINE(func, body)
+

 /**
     @c wxEXPLICIT is a macro which expands to the C++ @c explicit keyword if
     the compiler supports it or nothing otherwise. Thus, it can be used even in
 /**
     @c wxEXPLICIT is a macro which expands to the C++ @c explicit keyword if
     the compiler supports it or nothing otherwise. Thus, it can be used even in