X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/398e314854788981104ad57751e914bcf9681930..c29c95fe24973b94fd724db767193171ca7c513d:/interface/wx/defs.h diff --git a/interface/wx/defs.h b/interface/wx/defs.h index 77c1148ce7..2513b04c38 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 0..255 corresponds to the characters of + the current locale, in particular the 32..127 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, @@ -742,6 +800,15 @@ enum wxPaperSize wxPAPER_PENV_10_ROTATED ///< PRC Envelope #10 Rotated 458 x 324 m }; +/** + Printing orientation +*/ + +enum wxPrintOrientation +{ + wxPORTRAIT, + wxLANDSCAPE +}; /** Duplex printing modes. @@ -776,6 +843,34 @@ 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 @@ -927,9 +1022,9 @@ typedef double wxDouble; 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 @@ -954,27 +1049,47 @@ typedef double wxDouble; private: // widgets can't be copied - DECLARE_NO_COPY_CLASS(FooWidget) + wxDECLARE_NO_COPY_CLASS(FooWidget); }; @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 - 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. + + @see wxDECLARE_NO_COPY_TEMPLATE_CLASS_2 */ -#define DECLARE_NO_COPY_TEMPLATE_CLASS(classname, arg) +#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 wxDECLARE_NO_COPY_TEMPLATE_CLASS_2(classname, arg1, arg2) /** A function which deletes and nulls the pointer. @@ -1063,7 +1178,7 @@ template wxDELETEA(T*& array); public: // OldMethod() is deprecated, use NewMethod() instead void NewMethod(); - wxDEPRECATED_INLINE( void OldMethod(), NewMethod() ); + wxDEPRECATED_INLINE( void OldMethod(), NewMethod(); ) }; @endcode @@ -1071,6 +1186,40 @@ template wxDELETEA(T*& array); */ #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